Skip to content
apomesh

Contribute

This section is for developers working on apomesh — the substrate, the orchestrator, the workers, the stores, the SDKs, the console — rather than building agents on top of it. If you are integrating against apomesh, start in Build; if you run the stack, start in Operate.

What’s here

Section titled “What’s here”
  • Codebase orientation — the layer map from the wire up to the console, which crate owns which concern, and a reading order that gets you productive fast.
  • Testing — the test tiers (unit, doc, cassette replay, testcontainers, live-provider), the canonical runner, and when each tier runs.
  • Working on the docs — how this documentation site is built, kept in sync with main, and gated.

The canonical reference

Section titled “The canonical reference”

The authoritative, deep architecture reference is docs/architecture.md in the repository — closed-enum vocabularies, boundary-type taxonomy, flow diagrams, the security model, deployment topologies. It self-disclaims: the code wins where the two disagree.

This Contribute section is the progressive path into that reference, not a replacement for it. It curates and orients; the in-repo document carries the exhaustive detail and stays closest to the source. When you need the full picture of a subsystem, follow the pointers here into docs/architecture.md and then into the code itself.

Governance rules

Section titled “Governance rules”

apomesh defends its architecture with a set of always-loaded rules under .claude/rules/. Each rule declares a tier:

  • Invariant — a correctness contract (tenant isolation, sandboxing, closed-enum exhaustiveness, event-sourcing as the single source of truth, the credential plane). Never violated; a breach is a bug, not a trade-off.
  • Default — a heuristic or convention (scoping, workflow, style). Yields to a technically-defended better shape.

.claude/CLAUDE.md holds the project posture and the tier framing; .claude/rules/way-of-work.md is the collaboration baseline. The orientation page points at the specific rules that govern each layer.

Next steps

Section titled “Next steps”