Architecture Corpus

This directory is the Developer Guide substrate: a set of per-subsystem explainers that, together with the decision log in docs/adr/, let a new maintainer (human or AI) understand how ml-container-creator fits together — starting from one file's header and navigating outward in a few hops.

It is built incrementally by the consolidation program (ADR-002). Each wave that reshapes a subsystem adds or updates the matching explainer here and records the decision as an ADR. Wave 8 stitches these into a navigable Developer Guide.

How the pieces relate

• ADRs (docs/adr/ADR-NNN-*.md) record decisions: the why, the alternatives, the consequences. They are dated and immutable once accepted.
• Architecture explainers (docs/architecture/*.md) describe how a subsystem works today. They are living documents, kept in sync with the code.
• Module headers (see module-header-convention.md) are the file-level entrypoint: each pattern-participating module names its pattern, collaborators, data-flow role, and a See: link into this corpus.

Contents

Conventions

• Module-Header Docblock Convention — the self-documenting-file standard and its ESLint enforcement.

System

• System Overview — the layer map: CLI shell → config/ intent → writing/template → codegen boundary → MCP boundary.

Subsystems (added as waves land)

• MCP picker servers — Wave 2
• Serve-engine plugins — Wave 3 — LLM/transformer serving engines
  • Authoring guide — extend/version/add engine plugins
• Predictor-framework plugins — classical-ML (sklearn/xgboost/tensorflow) HTTP predictors (descriptor + handler)
• Command handlers & do/config — Wave 4
• Validation framework — Wave 5
• do/ scripts — Wave 6
  • Adding a deployment target — the target authoring guide
  • Per-script Wave 6 changelog — what changed, per script
• Advisory agent — Wave 7 (agent.md)

Decision log

See the ADR log:

• ADR-001 — Import metadata contract (pre-program).
• ADR-002 — Consolidation & self-documenting re-architecture program (this program).
• ADR-003 — MCP picker-server factory (Wave 2).
• ADR-004 — Serve-engine plugin parity (Wave 3).
• ADR-005 — Command-handler contract (Wave 4).
• ADR-006 — Unified validation framework (Wave 5).
• ADR-007 — do/ script contract enforcement (Wave 6).
• ADR-008 — deployment-target descriptor / single source of truth (Wave 8).