Repo map: how the pieces fit together

Ecosystem overview showing dependencies between spec, schemas, codegen, SDKs, and runtime components.

A tour from the source of truth outward: the spec defines the wire format, the schema registry makes it machine-checkable, codegen turns that into typed SDK code, and every runtime component (adapters, the relay, bridges, the CLI, MCP) consumes the same generated types. Read this before touching code, to see what depends on what.

The chain: spec to running code

spec/ is normative. AEP-0001 through AEP-0005 define the envelope, the mandatory type set, bindings, the control profile, and the CE/OTLP mappings. Nothing here restates them; see STYLE.md for why.

schemas/ is the machine-readable projection of the taxonomy part of the spec: aep-event.schema.json (the envelope), registry/types.json (the type list with status/category/schema pointers), and types/*.schema.json (one payload schema per mandatory type, each field annotated x-aep-capture: none|metadata|redacted|full). schemas/codegen/generate.py reads these inputs (the envelope schema, the registry lists in registry/*.json, and the payload schemas) and emits schemas/gen/ts/aep-types.ts, schemas/gen/python/aep_types.py, and schemas/gen/asyncapi.yaml deterministically: identical input is byte-identical output (the header comment in each generated file says so, and CI diffs against a fresh run). Generated files are never hand-edited.

The SDKs (sdk/ts/, sdk/python/) copy the generated file into their own tree (sdk/ts/src/gen/aep-types.ts, sdk/python/aep_sdk/gen/aep_types.py) and layer hand-written emit/consume/ control modules on top; see sdk.md for that layering.

Everything under impl/ (the relay, the twelve adapters, the eight bridge sidecars (two outbound, six inbound), the CLI, aep-mcp) builds and parses the same envelope shape by hand against impl/shared/aep.js, not the generated TS/Python types, because impl/ predates the SDKs and is plain Node. impl/shared/aep.js:223 (envelopeError) is the implementation's own structural check, independent of the generated validators.

conformance/ is the arbiter that both trees agree with the spec: conformance/fixtures/ holds pinned inputs/outputs (envelope cases, CE and OTLP round-trips, redaction corpora), and conformance/run.js / conformance/run.py are dual runners so neither language's toolchain is privileged.

Fixtures aren't optional: the GOVERNANCE §2 SEP rule requires every accepted spec change to land with its conformance fixtures in the same change. A taxonomy or wire-format change without a fixture is not accepted, full stop. That coupling keeps schemas/ (and therefore the generated types and every SDK/impl consumer) from drifting silently out of sync with spec/.

graph TD
    spec["spec/ (AEP-0001..0005)"] --> schemas["schemas/\n(aep-event.schema.json,\nregistry/, types/)"]
    schemas --> codegen["schemas/codegen/generate.py"]
    codegen --> ts["gen/ts/aep-types.ts"]
    codegen --> py["gen/python/aep_types.py"]
    codegen --> asyncapi["gen/asyncapi.yaml"]
    ts --> sdkts["sdk/ts\n(emit/consume/control)"]
    py --> sdkpy["sdk/python\n(emit/consume/control)"]
    schemas --> impl["impl/ (relay, adapters,\nbridges, cli, mcp)"]
    schemas --> conformance["conformance/\n(fixtures + run.js/run.py)"]
    sdkts --> conformance
    sdkpy --> conformance
    impl --> conformance

Component directories

impl/README.md is the authoritative per-directory map with spec references; this grid mirrors it at a glance and links to the matching component doc:

impl/shared/ (attr-match, envelope checks, capture down-leveling, redaction, the CE/OTLP mapping helpers, the SSE client, ULID) has no dedicated page. It is referenced from whichever component doc uses each function.

See also

• What AEP is, and why: the problem the whole chain above exists to solve.
• GOVERNANCE.md: the SEP rule and the governance firewall between spec and code.
• Normative source: all of spec/.