architecture-diagrams

name	architecture-diagrams
description	Use when asked to generate or update architecture diagrams or ER (entity-relationship) diagrams from the codebase — the code is the source of truth, not existing docs.

Architecture & ER Diagram Generator

Derives diagrams directly from code — models/schemas for ER diagrams, module/service boundaries and call relationships for architecture diagrams. Treat any existing diagram as potentially stale; verify against code.

Steps — ER diagrams

1. Locate schema sources of truth: ORM models, migration files, schema.sql, or database schema introspection — in that order of preference.
2. Extract entities, fields, types, and relationships (FKs, has-many/belongs-to).
3. Render as a Mermaid erDiagram block:

   erDiagram
     USER ||--o{ ORDER : places
     ORDER ||--|{ LINE_ITEM : contains
   

4. Note any relationship that's enforced in code/app-logic but not in the DB schema (or vice versa) — that mismatch is often exactly what an EM wants surfaced.

Steps — Architecture diagrams

1. Map the real boundaries: services/packages/modules and how they actually communicate (imports, HTTP calls, message queues, shared DB) — grep for actual call sites, don't rely on folder names alone.
2. Render as a Mermaid graph / flowchart:

   flowchart LR
     API[API Service] --> DB[(Postgres)]
     API --> Queue[[Job Queue]]
     Worker --> Queue
     Worker --> DB
   

3. Keep it at the altitude that's useful — service-level by default; only drop to module-level if asked, since over-detailed diagrams go stale fast and become harder to read than the code itself.

Notes

• Always cite the files you derived each entity/edge from, so the diagram is checkable against the code that produced it.
• If the codebase contradicts an existing diagram/doc, say so explicitly — that's the valuable finding, not just the pretty picture.