gh-tachyon-beep-skillpacks-plugins-axiom-system-archaeologist/skills/using-system-archaeologist/generating-architecture-diagrams.md

Generating Architecture Diagrams

Purpose

Generate C4 architecture diagrams (Context, Container, Component levels) from subsystem catalogs, producing readable visualizations that communicate architecture without overwhelming readers.

When to Use

• Coordinator delegates diagram generation from 02-subsystem-catalog.md
• Task specifies writing to 03-diagrams.md
• Need to visualize system architecture at multiple abstraction levels
• Output integrates with validation and final reporting phases

Core Principle: Abstraction Over Completeness

Readable diagrams communicate architecture. Overwhelming diagrams obscure it.

Your goal: Help readers understand the system, not document every detail.

Output Contract

When writing to 03-diagrams.md, include:

Required sections:

1. Context Diagram (C4 Level 1): System boundary, external actors, external systems
2. Container Diagram (C4 Level 2): Major subsystems with dependencies
3. Component Diagrams (C4 Level 3): Internal structure for 2-3 representative subsystems
4. Assumptions and Limitations: What you inferred, what's missing, diagram constraints

For each diagram:

• Title (describes what the diagram shows)
• Mermaid or PlantUML code block (as requested)
• Description (narrative explanation after diagram)
• Legend (notation explained)

C4 Level Selection

Level 1: Context Diagram

Purpose: System boundary and external interactions

Show:

• The system as single box
• External actors (users, administrators)
• External systems (databases, services, repositories)
• High-level relationships

Don't show:

• Internal subsystems (that's Level 2)
• Implementation details

Example scope: "User Data Platform and its external dependencies"

Level 2: Container Diagram

Purpose: Major subsystems and their relationships

Show:

• Internal subsystems/services/plugins
• Dependencies between them
• External systems they connect to

Abstraction strategies:

• Simple systems (≤8 subsystems): Show all subsystems individually
• Complex systems (>8 subsystems): Use grouping strategies:
  • Group by category/domain (e.g., faction, layer, purpose)
  • Add metadata to convey scale (e.g., "13 skills", "9 services")
  • Reduce visual elements while preserving fidelity

Don't show:

• Internal components within subsystems (that's Level 3)
• Every file or class

Example scope: "15 plugins organized into 6 domain categories"

Level 3: Component Diagrams

Purpose: Internal architecture of selected subsystems

Selection criteria (choose 2-3 subsystems that):

1. Architectural diversity - Show different patterns (router vs orchestrator, sync vs async)
2. Scale representation - Include largest/most complex if relevant
3. Critical path - Entry points, security-critical, data flow bottlenecks
4. Avoid redundancy - Don't show 5 examples of same pattern

Show:

• Internal components/modules/classes
• Relationships between components
• External dependencies for context

Document selection rationale:

**Selection Rationale**:
- Plugin A: Largest (13 skills), shows router pattern
- Plugin B: Different organization (platform-based vs algorithm-based)
- Plugin C: Process orchestration (vs knowledge routing)

**Why Not Others**: 8 plugins follow similar pattern to A (redundant)

Abstraction Strategies for Complexity

When facing many subsystems (10+):

Strategy 1: Natural Grouping

Look for existing structure:

• Categories in metadata (AI/ML, Security, UX)
• Layers (presentation, business, data)
• Domains (user management, analytics, reporting)

Example:

subgraph "AI/ML Domain"
    YzmirRouter[Router: 1 skill]
    YzmirRL[Deep RL: 13 skills]
    YzmirLLM[LLM: 8 skills]
end

Benefit: Aligns with how users think about the system

Strategy 2: Metadata Enrichment

Add context without detail:

• Skill counts: "Deep RL: 13 skills"
• Line counts: "342 lines"
• Status: "Complete" vs "WIP"

Benefit: Conveys scale without visual clutter

Strategy 3: Strategic Sampling

For Component diagrams, sample ~20%:

• Choose diverse examples (not all similar)
• Document "Why these, not others"
• Prefer breadth over depth

Benefit: Readers see architectural variety without information overload

Notation Conventions

Relationship Types

Use different line styles for different semantics:

• Solid lines (-->) - Data dependencies, function calls, HTTP requests
• Dotted lines (-.->) - Routing relationships, optional dependencies, logical grouping
• Bold lines - Critical path, high-frequency interactions (if tooling supports)

Example:

Router -.->|"Routes to"| SpecializedSkill  # Logical routing
Gateway -->|"Calls"| AuthService          # Data flow

Color Coding

Use color to create visual hierarchy:

• Factions/domains - Different color per group
• Status - Green (complete), yellow (WIP), gray (external)
• Importance - Highlight critical paths

Document in legend: Explain what colors mean

Component Annotation

Add metadata in labels:

AuthService[Authentication Service<br/>Python<br/>342 lines]

Handling Incomplete Information

When Catalog Has Gaps

Inferred components (reasonable):

• Catalog references "Cache Service" repeatedly → Include in diagram
• MUST document: "Cache Service inferred from dependencies (not in catalog)"
• Consider notation: Dotted border or lighter color for inferred components

Missing dependencies (don't guess):

• Catalog says "Outbound: Unknown" → Document limitation
• Don't invent: Leave out rather than guess

When Patterns Don't Map Directly

Catalog says "Patterns Observed: Circuit breaker"

Reasonable: Add circuit breaker component to diagram (it's architectural)

Document: "Circuit breaker shown based on pattern observation (not explicit component)"

Documentation Template

After diagrams, include:

## Assumptions and Limitations

### Assumptions
1. **Component X**: Inferred from Y references in catalog
2. **Protocol**: Assumed HTTP/REST based on API Gateway pattern
3. **Grouping**: Used faction categories from metadata

### Limitations
1. **Incomplete Catalog**: Only 5/10 subsystems documented
2. **Missing Details**: Database schema not available
3. **Deployment**: Scaling/replication not shown

### Diagram Constraints
- **Format**: Mermaid syntax (may not render in all viewers)
- **Abstraction**: Component diagrams for 3/15 subsystems only
- **Trade-offs**: Visual clarity prioritized over completeness

### Confidence Levels
- **High**: Subsystems A, B, C (well-documented)
- **Medium**: Subsystem D (some gaps in dependencies)
- **Low**: Subsystem E (minimal catalog entry)

Mermaid vs PlantUML

Default to Mermaid unless task specifies otherwise.

Mermaid advantages:

• Native GitHub rendering
• Simpler syntax
• Better IDE support

PlantUML when requested:

@startuml
!include <C4/C4_Context>

Person(user, "User")
System(platform, "Platform")
Rel(user, platform, "Uses")
@enduml

Success Criteria

You succeeded when:

• All 3 C4 levels generated (Context, Container, Component for 2-3 subsystems)
• Diagrams are readable (not overwhelming)
• Selection rationale documented
• Assumptions and limitations section present
• Syntax valid (Mermaid or PlantUML)
• Titles, descriptions, legends included
• Written to 03-diagrams.md

You failed when:

• Skipped diagram levels
• Created overwhelming diagrams (15 flat boxes instead of grouped)
• No selection rationale for Component diagrams
• Invalid syntax
• Missing documentation sections
• Invented relationships without noting as inferred

Best Practices from Baseline Testing

What Works

✅ Faction-based grouping - Reduce visual complexity (15 → 6 groups) ✅ Metadata enrichment - Skill counts, line counts convey scale ✅ Strategic sampling - 20% Component diagrams showing diversity ✅ Clear rationale - Document why you chose these examples ✅ Notation for relationships - Dotted (routing) vs solid (data) ✅ Color hierarchy - Visual grouping by domain ✅ Trade-off documentation - Explicit "what's visible vs abstracted"

Common Patterns

Router pattern visualization:

• Show router as distinct component
• Use dotted lines for routing relationships
• Group routed-to components

Layered architecture:

• Use subgraphs for layers
• Show dependencies flowing between layers
• Don't duplicate components across layers

Microservices:

• Group related services by domain
• Show API gateway as entry point
• External systems distinct from internal services

Integration with Workflow

This skill is typically invoked as:

1. Coordinator completes subsystem catalog (02-subsystem-catalog.md)
2. Coordinator validates catalog (optional validation gate)
3. Coordinator writes task specification for diagram generation
4. YOU read catalog systematically
5. YOU generate diagrams following abstraction strategies
6. YOU document assumptions, limitations, selection rationale
7. YOU write to 03-diagrams.md
8. Validator checks diagrams for syntax, completeness, readability

Your role: Translate catalog into readable visual architecture using abstraction and selection strategies.