ISA-Frontend/.claude/skills/architecture-documentation/SKILL.md

name, description

name	description
architecture-documentation	Generate architecture documentation (C4, Arc42, ADRs, PlantUML). Auto-invoke when user mentions "architecture docs", "C4 model", "ADR", "document architecture", "system design", or "create architecture diagram".

Architecture Documentation Skill

Generate comprehensive architecture documentation using modern frameworks and best practices.

When to Use

• Creating or updating architecture documentation
• Generating C4 model diagrams (Context, Container, Component, Code)
• Writing Architecture Decision Records (ADRs)
• Documenting system design and component relationships
• Creating PlantUML or Mermaid diagrams

Available Frameworks

C4 Model

Best for: Visualizing software architecture at different abstraction levels

Levels:

1. Context - System landscape and external actors
2. Container - High-level technology choices (apps, databases, etc.)
3. Component - Internal structure of containers
4. Code - Class/module level detail (optional)

See: @references/c4-model.md for patterns and examples

Arc42 Template

Best for: Comprehensive architecture documentation

Sections:

1. Introduction and Goals
2. Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Cross-cutting Concepts
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary

See: @references/arc42.md for template structure

Architecture Decision Records (ADRs)

Best for: Documenting individual architectural decisions

See: @references/adr-template.md for format and examples

Workflow

1. Discovery Phase

# Find existing architecture files
find . -name "*architecture*" -o -name "*.puml" -o -name "*.mmd"

# Identify service boundaries
cat nx.json docker-compose.yml

# Check for existing ADRs
ls -la docs/adr/ docs/decisions/

2. Analysis Phase

• Analyze codebase structure (libs/, apps/)
• Identify dependencies from tsconfig.base.json paths
• Review service boundaries from project.json tags
• Map data flow from API definitions

3. Documentation Phase

Based on the request, create appropriate documentation:

For C4 diagrams:

docs/architecture/
├── c4-context.puml
├── c4-container.puml
└── c4-component-[name].puml

For ADRs:

docs/adr/
├── 0001-record-architecture-decisions.md
├── 0002-[decision-title].md
└── template.md

For Arc42:

docs/architecture/
└── arc42/
    ├── 01-introduction.md
    ├── 02-constraints.md
    └── ...

ISA-Frontend Specific Context

Monorepo Structure

• apps/: Angular applications
• libs/: Shared libraries organized by domain
  • libs/[domain]/feature/ - Feature modules
  • libs/[domain]/data-access/ - State management
  • libs/[domain]/ui/ - Presentational components
  • libs/[domain]/util/ - Utilities

Key Architectural Patterns

• Nx Monorepo with strict module boundaries
• NgRx Signal Store for state management
• Standalone Components (Angular 20+)
• Domain-Driven Design library organization

Documentation Locations

• ADRs: docs/adr/
• Architecture diagrams: docs/architecture/
• API documentation: Generated from Swagger/OpenAPI

Output Standards

PlantUML Format

@startuml C4_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(user, "User", "System user")
System(system, "ISA System", "Main application")
System_Ext(external, "External API", "Third-party service")

Rel(user, system, "Uses")
Rel(system, external, "Calls")
@enduml

Mermaid Format

graph TD
    A[User] --> B[ISA App]
    B --> C[API Gateway]
    C --> D[Backend Services]

ADR Format

# ADR-XXXX: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
[What is the issue?]

## Decision
[What was decided?]

## Consequences
[What are the results?]

Best Practices

1. Start with Context - Always begin with C4 Level 1 (System Context)
2. Use Consistent Notation - Stick to one diagramming tool/format
3. Keep ADRs Atomic - One decision per ADR
4. Version Control - Commit documentation with code changes
5. Review Regularly - Architecture docs decay; schedule reviews