# 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, spawned by vav-pipeline as an Erlang Port (staged into the pod by the `shoresh-engine-install` init container — NOT a sidecar container; a Port is a child process of the BEAM and cannot cross a container boundary) | 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. vav-pipeline is the main container; talmudic-engine and korban-processor are sidecars; shoresh-engine runs inside vav-pipeline as an Erlang Port child process, staged in by an init container.

## 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 namespace
- `configmap.yaml` — non-secret configuration
- `secrets.yaml` — **template only**; operator fills in `DATABASE_URL`
- `l1-volume.yaml` — PV and PVC for Torah filesystem
- `manna-volume.yaml` — PVC for provision file
- `deployment.yaml` — the pod with 3 containers + 2 init containers (`shoresh-engine-install`, `migrate`). Four images are still built and pushed; shoresh-engine ships a binary, not a running container.
- `service.yaml` — ClusterIP and external LoadBalancer
- `gitea-mcp-deployment.yaml` — separate MCP server for Gitea connector (optional)
- `gitea-mcp-ingress.yaml` — TLS ingress for the MCP server
- `gitea-mcp-secret.yaml` — template for Gitea PAT
- `cert-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 release
- `Dockerfile.shoresh_engine` — multi-stage Haskell GHC 9.6.4 / Cabal
- `Dockerfile.talmudic_engine` — SWI-Prolog 9.2.2 with socket server
- `Dockerfile.korban_processor` — Python 3.12.2 slim

## Configuration surface

The system reads three things from its environment:

1. **L1 Torah** — mounted read-only at `$L1_MOUNT_POINT`. Integrity verified at every boot.
2. **Manna provision** — JSON file at `$MANNA_PROVISION_FILE`, written by the kohen/treasurer.
3. **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.