Diagram Maintenance

The architecture diagrams are maintained as Mermaid source embedded in Markdown. They are documentation, not generated artifacts:

  • docs/database-erd.md contains the application-level entity-relationship overview and its focused aspect diagrams.
  • docs/c4/l1-c4-context.md describes people, the system boundary, and external systems.
  • docs/c4/l2-c4-container.md describes runtime processes, stores, and interfaces.
  • docs/c4/l3-c4-component.md describes the main components and behavioral data flows inside those containers.

Update the diagrams whenever a change makes their current description materially incorrect. Typical triggers include a model or relationship change, a new external integration, a new runtime process or persistent store, a changed trust boundary, or a significant redistribution of responsibilities between components.

Updating the ER Diagrams

Treat Django models and database migrations as the source of truth. Do not infer relationships from forms, serializers, or browser code.

  1. Inventory first-party models:

bash rg -n '^class .+\(models\.Model\)' apps --glob 'models.py'

  1. Read each changed model and its migrations. Record primary keys, foreign keys, one-to-one fields, many-to-many fields, spatial fields, state fields, unique constraints, conditional constraints, and database indexes that affect the documented structure.
  2. Update the relationship-only overview in docs/database-erd.md. Keep entities without foreign keys visible as standalone declarations.
  3. Update every affected aspect diagram. Use an EXT_* entity when a foreign key crosses an aspect boundary, so the outbound relationship remains visible without duplicating the full external entity.
  4. Update the focused parcel versioning/topology diagram and the documented database rules when temporal, lineage, topology, overlap, or uniqueness behavior changes.
  5. Compare the final entity list with the model inventory. Every first-party model should appear in the complete overview, and every relationship shown should be traceable to a model field or Django authentication relationship.

Use Mermaid ER cardinality consistently:

Notation Meaning
|| exactly one
o| zero or one
o{ zero or many

Updating the C4 Diagrams

The C4 documents describe what the running system does, rather than the internal implementation of individual functions. Verify architectural claims directly against code before changing a diagram.

For a routine update:

  1. Identify the changed entry points, runtime boundaries, data stores, external calls, authorization boundaries, transactions, and state transitions.
  2. Update L1 only when actors, external systems, trust boundaries, or the system's responsibility change.
  3. Update L2 when a runtime process, persistent store, external runtime, interface, concurrency rule, or transaction boundary changes.
  4. Update L3 when component responsibilities, component interactions, state transitions, failure behavior, or principal data flows change.
  5. Update each document's Evidence section with current path:line references. Remove references that no longer support the associated claim.
  6. Check that every L1 external system is represented at L2, every L2 application container is decomposed at L3, and every L3 component participates in a documented flow.

Keep the existing Mermaid class definitions, node styles, and short lowercase node identifiers. Labels should state the architectural responsibility and may name the relevant technology. Preserve the ASCII fallback when changing the L2 primary data flow.

For a broad architectural change, rerun a full reverse-engineering pass instead of incrementally patching the diagrams. In Codex, request the c4-reverse-engineer skill with:

Regenerate the C4 diagrams for general architecture documentation, diagrams only. Preserve project-specific scope and verify every claim directly against the current code.

The full workflow surveys entry points and integrations, verifies behavioral claims against direct code reads, regenerates L1 through L3, and performs a cross-artifact consistency review. Review its proposed changes rather than accepting wholesale replacement: the current C4 scope intentionally focuses on versioned land parcel management, not every framework or test component.

Validation

Run the smallest checks that cover the documentation changes:

rg -n '^```mermaid|^```$' docs/database-erd.md docs/c4
git diff --check
make docs-build

Confirm manually that:

  • Mermaid fences are balanced and each diagram renders.
  • Diagram labels remain readable at the documentation site's normal width.
  • The ER complete overview covers every first-party model.
  • ER relationships and cardinalities match current model fields.
  • C4 levels remain mutually consistent.
  • C4 evidence references point to the code that supports each claim.

make docs-build checks the documentation site but may not detect every Mermaid syntax or layout problem. If a Mermaid renderer or CLI is available in the development environment, render every changed diagram as an additional visual check. Mermaid CLI is not currently a project dependency; do not add it solely for this check without project-owner approval.