andresnator Architecture Map
Contract
Create system context, containers, representative runtime flows from verified code evidence. No code-level design, user story mapping, or AI-harness analysis.
- Each node and edge cites manifest, config, import, entrypoint, deployment descriptor, or underlying
file:lineresolved through healthy graph. Mark anything elsehypothesis. - Use GitHub-renderable Mermaid
flowchartandsequenceDiagramonly. - Maximum about 30 nodes per diagram and 120 lines per file. Split before exceeding either.
- Write to
docs/architecture/whendocs/exists; create that child as needed. Otherwise use existingdoc/architecture/, or create it when neither root exists.
Shape
Default: one index.md containing system context, containers, 1-3 key flows. Use skeleton in assets/architecture-doc-set.md.
Split only when the default exceeds a budget:
- Move context and containers to
overview.md. - Move flows to
flows.md. - For multiple deployables, keep workspace context in
index.md; addprojects/<name>.mdonly when one diagram cannot stay within budget.
Cross-project edges need manifest, config, deployment, topic, URL, or shared-schema evidence. Per-project graph never proves them.
Refresh
Regenerate from current evidence; diff against recorded source commit; update changed files only; never remove manually owned files. Report added/removed containers, dependency changes, flow changes.
Output
Return docfolder, files written or updated, initial generation or drift summary, hypotheses. Verify balanced Mermaid blocks, cross-links when split, budgets, source commit.