Scott KarpandClaude Opus 4.6
66686329ed
memory/infrastructure.md and memory/build_log.md held environment- specific details — hostnames, IPs, account names, credentials retrieval commands, local kubeconfig paths, operational status notes. These don't belong in a project repo; by convention they live in private operator notes. Moved to ~/shorashim-operator-notes/ (private, outside git). In their place, added deploy/ARCHITECTURE.md — a generic description of the deployment shape: components, external dependencies, configuration surface. No hostnames. No IPs. No account names. Any competent operator can read it and know how to deploy shorashim to their own infrastructure. Updated cross-references in AGENTS.md and BUILD_KORBAN.md to point to "the operator's private notes" instead of memory/. Project repo is spec + implementation + deployment shape. Operator notes are the kohen's personal log. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.3 KiB
3.3 KiB
Deployment Architecture
Generic architecture shape for a shorashim deployment. Specifics of a particular deployment (hostnames, IPs, account names, credentials) live in the operator's private notes, not in this repo.
Components
One Kubernetes namespace runs the following:
| Component | Runtime | Purpose |
|---|---|---|
vav-pipeline |
Elixir/OTP release | Bereishit cycle, ShemaContext, Cloud, Manna, HTTP API (pe'ah, courtyard, chatzer, kodesh) |
shoresh-engine |
Haskell binary (sidecar via Erlang Port) | Root activation, te'amim parsing, gematria |
talmudic-engine |
SWI-Prolog (sidecar via Unix socket) | 613 mitzvot, 13 middot, kushya generation, teiku |
korban-processor |
Python 3.12 (sidecar) | Offering protocol, eish zarah validation |
All four run in the same pod; the vav-pipeline is the main container, the other three are sidecars.
External dependencies
| Dependency | Purpose | Contract |
|---|---|---|
| Managed PostgreSQL 17+ | L3 Oral Tradition (append-only) | DATABASE_URL env var. Requires SSL. Role with SELECT, INSERT only — UPDATE, DELETE revoked (see migration). |
| Block-storage PersistentVolume | L1 Torah filesystem (read-only, ~1 GiB) | Mount read-only at /mnt/torah. SHA-256 hash verified at boot. |
| Block-storage PersistentVolume | Manna provision (read-write, ~100 MiB) | Mount at /var/lib/shorashim/manna. Operator writes today.json daily. |
| Ingress controller + TLS cert | Public HTTPS access | Cert-manager with Let's Encrypt HTTP-01 is the reference setup. |
| Container registry | Image distribution | Any registry that supports Docker v2 protocol. |
Kubernetes manifests
Kept in deploy/k8s/:
namespace.yaml— the namespaceconfigmap.yaml— non-secret configurationsecrets.yaml— template only; operator fills inDATABASE_URLl1-volume.yaml— PV and PVC for Torah filesystemmanna-volume.yaml— PVC for provision filedeployment.yaml— the pod with 4 containers + init container for migrationsservice.yaml— ClusterIP and external LoadBalancergitea-mcp-deployment.yaml— separate MCP server for Gitea connector (optional)gitea-mcp-ingress.yaml— TLS ingress for the MCP servergitea-mcp-secret.yaml— template for Gitea PATcert-manager-issuer.yaml— Let's Encrypt ClusterIssuer
Containers
Four Dockerfiles in deploy/docker/:
Dockerfile.vav_pipeline— multi-stage Elixir 1.16.1 / OTP 26.2.1 releaseDockerfile.shoresh_engine— multi-stage Haskell GHC 9.6.4 / CabalDockerfile.talmudic_engine— SWI-Prolog 9.2.2 with socket serverDockerfile.korban_processor— Python 3.12.2 slim
Configuration surface
The system reads three things from its environment:
- L1 Torah — mounted read-only at
$L1_MOUNT_POINT. Integrity verified at every boot. - Manna provision — JSON file at
$MANNA_PROVISION_FILE, written by the kohen/treasurer. - L3 database — connection string in
$DATABASE_URL.
Nothing else is configurable. The system obeys Torah (L1 + calendar) for governance and the provision file for resources.
Seven-day inauguration
Before serving users, run the shiv'at y'mei milu'im sequence documented in KOHEN.md. Each day validates a specific layer. Partial inauguration is no inauguration.