---
name: architecture-documentation
description: 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
```bash
# 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
```plantuml
@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
```mermaid
graph TD
    A[User] --> B[ISA App]
    B --> C[API Gateway]
    C --> D[Backend Services]
```

### ADR Format
```markdown
# 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
