Architecture overview documented

Severity: Recommended

New developers need to understand how the system fits together before diving into code. An architecture doc provides the mental model.

Check automatically:

# Look for architecture docs
find . -maxdepth 4 -type f \( -name "*architect*" -o -name "*overview*" -o -name "*system*" -o -name "*design*" \) -name "*.md" 2>/dev/null | grep -v node_modules

# Search for architecture content
grep -riE "architecture|system (design|overview)|high.level|component" docs/ README.md --include="*.md" 2>/dev/null | head -10

# Check for diagrams
find . -maxdepth 4 -type f \( -name "*.mermaid" -o -name "*.puml" -o -name "*.drawio" \) 2>/dev/null | grep -v node_modules
ls -la docs/*diagram* docs/*architect* 2>/dev/null

Ask user:

• "Is there a document explaining how the system fits together?"
• "Does it include diagrams?" (boxes and arrows, sequence diagrams)
• "Would a new dev understand the major components after reading it?"

Pass criteria:

• Architecture doc exists (in repo or linked wiki/Notion)
• Covers major components and how they interact
• Diagram or visual representation included
• Understandable without prior context

Fail criteria:

• No architecture doc ("it's in people's heads")
• Doc exists but outdated (describes old system)
• Text-only, no visual representation
• Requires existing knowledge to understand

Cross-reference with:

• DEV-004 (architecture references key systems)
• DOC-001/DOC-002 (general documentation standards)

Evidence to capture:

• Location of architecture doc
• Last updated date
• Whether diagrams exist
• Components covered (frontend, backend, DB, queues, external services)

---