Choco Factory Architecture Map

ELI5

Choco is a chocolate factory laid out in seven rooms. Every package — beans, fudge, golden tickets — gets passed from one room to the next over a single conveyor belt called NATS. Each room is one service, and the room name tells you what it does to the chocolate as it goes by.

Technical Deep Dive

Choco-hq is the top-of-tree repo for a 7-layer, ~31-repo platform (README.md:38-50). Application services live under services/, contracts under contracts/, event protos under proto/events/, and decisions under architecture/decisions/.

Layer Map

flowchart TB
    subgraph edge["Edge & Delivery (CF Workers, R2, KV, Pages)"]
      cw[choco-edge-gateway]
      cl[choco-landing]
    end
    subgraph api["API Gateway (Go)"]
      gw[choco-gateway]
      al[airlock]
    end
    subgraph core["Core Document Engine (Rust)"]
      cmp[choco-compiler]
      vlt[choco-vault]
      srch[choco-search]
      sync[choco-sync]
    end
    subgraph factory["Factory Equipment (Go/Python)"]
      conch[the-conch]
      mould[the-mould]
      winn[the-winnower]
      wrap[the-wrapper]
    end
    subgraph plat["Platform & Integrations"]
      gp[golden-press]
      cons[choco-consumers]
    end
    subgraph fe["Frontend & DX"]
      web[cho-co-web]
      cli[choco-cli]
      sdk[the-cocoa-bean]
    end
    subgraph shared["Shared Runtime"]
      cb[cocoa-butter]
    end
    edge --> api --> core
    api --> factory
    factory --> plat
    fe --> api
    sdk --> api
    shared -.-> api
    shared -.-> factory

Convention by Repo Name

The factory metaphor is load-bearing in code, not just docs. the-conch/README.md:4 declares factory.room = "Fudge Room" as a structured-log field bootstrapped at startup; the same pattern repeats in the-mould, the-winnower, the-wrapper. Shared runtime helpers (NATS publisher, OTel tracer, log scaffolding) live in cocoa-butter and are imported by every factory-equipment service.

Per-Service Port Convention

Sources: respective services/<name>/README.md Ports tables.

Key Terms

• factory equipment → cluster of single-purpose Go/Python services that operate on documents in transit between vault and edge.
• cocoa-butter → shared runtime library re-imported by every service for NATS, OTel, structured logging.
• airlock → TypeScript auth/identity gatekeeper that owns GitHub/Polar OAuth tokens.

Q&A

Q: Why is factory.room set at bootstrap rather than per-log-call? A: It is a constant per process; bootstrapping it in the structured log scaffolding lets every line carry the room tag without ceremony at the call site (services/the-conch/README.md:21).

Q: Which layer owns Polar billing? A: Platform & Integrations — choco-billing is listed under that layer in README.md:46. airlock holds the OAuth token but does not run the metering pipeline.

Q: Where do contracts live? A: Top-level contracts/ (OpenAPI + JSON schema) and proto/events/ (NATS event protos). Generated code targets choco-contracts/gen/... per the proto go_package options.

Examples

When adding a new factory-equipment service, copy the port-convention block from any existing the-*/README.md, register a factory.room = "..." log field at bootstrap, and import cocoa-butter for the NATS publisher rather than wiring jetstream directly.