mirror of
https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend
synced 2025-12-28 22:42:11 +01:00
♻️ refactor: convert architecture-documentation from command to skill
Move architecture documentation generation from a slash command to a skill with comprehensive reference materials (C4 model, Arc42, ADR templates).
This commit is contained in:
Lorenz Hilpert
@@ -1,94 +0,0 @@
|
||||
---
|
||||
allowed-tools: Read, Write, Edit, Bash
|
||||
argument-hint: [framework] | --c4-model | --arc42 | --adr | --plantuml | --full-suite
|
||||
description: Generate comprehensive architecture documentation with diagrams, ADRs, and interactive visualization
|
||||
---
|
||||
|
||||
# Architecture Documentation Generator
|
||||
|
||||
Generate comprehensive architecture documentation: $ARGUMENTS
|
||||
|
||||
## Current Architecture Context
|
||||
|
||||
- Project structure: !`find . -type f -name "*.json" -o -name "*.yaml" -o -name "*.toml" | head -5`
|
||||
- Documentation exists: @docs/ or @README.md (if exists)
|
||||
- Architecture files: !`find . -name "*architecture*" -o -name "*design*" -o -name "*.puml" | head -3`
|
||||
- Services/containers: @docker-compose.yml or @k8s/ (if exists)
|
||||
- API definitions: !`find . -name "*api*" -o -name "*openapi*" -o -name "*swagger*" | head -3`
|
||||
|
||||
## Task
|
||||
|
||||
Generate comprehensive architecture documentation with modern tooling and best practices:
|
||||
|
||||
1. **Architecture Analysis and Discovery**
|
||||
- Analyze current system architecture and component relationships
|
||||
- Identify key architectural patterns and design decisions
|
||||
- Document system boundaries, interfaces, and dependencies
|
||||
- Assess data flow and communication patterns
|
||||
- Identify architectural debt and improvement opportunities
|
||||
|
||||
2. **Architecture Documentation Framework**
|
||||
- Choose appropriate documentation framework and tools:
|
||||
- **C4 Model**: Context, Containers, Components, Code diagrams
|
||||
- **Arc42**: Comprehensive architecture documentation template
|
||||
- **Architecture Decision Records (ADRs)**: Decision documentation
|
||||
- **PlantUML/Mermaid**: Diagram-as-code documentation
|
||||
- **Structurizr**: C4 model tooling and visualization
|
||||
- **Draw.io/Lucidchart**: Visual diagramming tools
|
||||
|
||||
3. **System Context Documentation**
|
||||
- Create high-level system context diagrams
|
||||
- Document external systems and integrations
|
||||
- Define system boundaries and responsibilities
|
||||
- Document user personas and stakeholders
|
||||
- Create system landscape and ecosystem overview
|
||||
|
||||
4. **Container and Service Architecture**
|
||||
- Document container/service architecture and deployment view
|
||||
- Create service dependency maps and communication patterns
|
||||
- Document deployment architecture and infrastructure
|
||||
- Define service boundaries and API contracts
|
||||
- Document data persistence and storage architecture
|
||||
|
||||
5. **Component and Module Documentation**
|
||||
- Create detailed component architecture diagrams
|
||||
- Document internal module structure and relationships
|
||||
- Define component responsibilities and interfaces
|
||||
- Document design patterns and architectural styles
|
||||
- Create code organization and package structure documentation
|
||||
|
||||
6. **Data Architecture Documentation**
|
||||
- Document data models and database schemas
|
||||
- Create data flow diagrams and processing pipelines
|
||||
- Document data storage strategies and technologies
|
||||
- Define data governance and lifecycle management
|
||||
- Create data integration and synchronization documentation
|
||||
|
||||
7. **Security and Compliance Architecture**
|
||||
- Document security architecture and threat model
|
||||
- Create authentication and authorization flow diagrams
|
||||
- Document compliance requirements and controls
|
||||
- Define security boundaries and trust zones
|
||||
- Create incident response and security monitoring documentation
|
||||
|
||||
8. **Quality Attributes and Cross-Cutting Concerns**
|
||||
- Document performance characteristics and scalability patterns
|
||||
- Create reliability and availability architecture documentation
|
||||
- Document monitoring and observability architecture
|
||||
- Define maintainability and evolution strategies
|
||||
- Create disaster recovery and business continuity documentation
|
||||
|
||||
9. **Architecture Decision Records (ADRs)**
|
||||
- Create comprehensive ADR template and process
|
||||
- Document historical architectural decisions and rationale
|
||||
- Create decision tracking and review process
|
||||
- Document trade-offs and alternatives considered
|
||||
- Set up ADR maintenance and evolution procedures
|
||||
|
||||
10. **Documentation Automation and Maintenance**
|
||||
- Set up automated diagram generation from code annotations
|
||||
- Configure documentation pipeline and publishing automation
|
||||
- Set up documentation validation and consistency checking
|
||||
- Create documentation review and approval process
|
||||
- Train team on architecture documentation practices and tools
|
||||
- Set up documentation versioning and change management
|
||||
171
.claude/skills/architecture-documentation/SKILL.md
Normal file
171
.claude/skills/architecture-documentation/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
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
|
||||
@@ -0,0 +1,213 @@
|
||||
# Architecture Decision Record (ADR) Template
|
||||
|
||||
## Overview
|
||||
|
||||
Architecture Decision Records document significant architectural decisions along with their context and consequences.
|
||||
|
||||
## ADR Format
|
||||
|
||||
### Standard Template
|
||||
|
||||
```markdown
|
||||
# ADR-XXXX: [Short Title]
|
||||
|
||||
## Status
|
||||
[Proposed | Accepted | Deprecated | Superseded by ADR-YYYY]
|
||||
|
||||
## Date
|
||||
YYYY-MM-DD
|
||||
|
||||
## Context
|
||||
What is the issue that we're seeing that is motivating this decision or change?
|
||||
|
||||
## Decision
|
||||
What is the change that we're proposing and/or doing?
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Benefit 1
|
||||
- Benefit 2
|
||||
|
||||
### Negative
|
||||
- Drawback 1
|
||||
- Drawback 2
|
||||
|
||||
### Neutral
|
||||
- Side effect 1
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Option 1: [Name]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
- Why rejected: ...
|
||||
|
||||
### Option 2: [Name]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
- Why rejected: ...
|
||||
|
||||
## References
|
||||
- [Link to related documentation]
|
||||
- [Link to discussion thread]
|
||||
```
|
||||
|
||||
## Example ADRs
|
||||
|
||||
### ADR-0001: Use Nx Monorepo
|
||||
|
||||
```markdown
|
||||
# ADR-0001: Use Nx Monorepo for Project Organization
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
2024-01-15
|
||||
|
||||
## Context
|
||||
The ISA Frontend consists of multiple applications and shared libraries. We need a way to:
|
||||
- Share code between applications
|
||||
- Maintain consistent tooling and dependencies
|
||||
- Enable efficient CI/CD with affected-based testing
|
||||
- Enforce architectural boundaries
|
||||
|
||||
## Decision
|
||||
We will use Nx as our monorepo tool with the following structure:
|
||||
- `apps/` - Deployable applications
|
||||
- `libs/` - Shared libraries organized by domain and type
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Single version of dependencies across all projects
|
||||
- Affected-based testing reduces CI time
|
||||
- Consistent tooling (ESLint, Prettier, TypeScript)
|
||||
- Built-in dependency graph visualization
|
||||
|
||||
### Negative
|
||||
- Learning curve for team members new to Nx
|
||||
- More complex initial setup
|
||||
- All code in single repository increases clone time
|
||||
|
||||
### Neutral
|
||||
- Requires discipline in library boundaries
|
||||
- Need to maintain `project.json` and tags
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Polyrepo
|
||||
- Pros: Simpler individual repos, independent deployments
|
||||
- Cons: Dependency management nightmare, code duplication
|
||||
- Why rejected: Too much overhead for code sharing
|
||||
```
|
||||
|
||||
### ADR-0002: Adopt NgRx Signal Store
|
||||
|
||||
```markdown
|
||||
# ADR-0002: Adopt NgRx Signal Store for State Management
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Date
|
||||
2024-03-01
|
||||
|
||||
## Context
|
||||
We need a state management solution that:
|
||||
- Integrates well with Angular signals
|
||||
- Provides predictable state updates
|
||||
- Supports devtools for debugging
|
||||
- Has good TypeScript support
|
||||
|
||||
## Decision
|
||||
We will use NgRx Signal Store for new features and gradually migrate existing stores.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Native signal integration
|
||||
- Simpler boilerplate than classic NgRx
|
||||
- Better performance with fine-grained reactivity
|
||||
- Excellent TypeScript inference
|
||||
|
||||
### Negative
|
||||
- Migration effort for existing NgRx stores
|
||||
- Different patterns from classic NgRx
|
||||
|
||||
### Neutral
|
||||
- Team needs to learn new API
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Classic NgRx (Store + Effects)
|
||||
- Pros: Mature, well-documented
|
||||
- Cons: Verbose boilerplate, doesn't leverage signals
|
||||
- Why rejected: Signal Store is the future direction
|
||||
|
||||
### Akita
|
||||
- Pros: Less boilerplate
|
||||
- Cons: Not Angular-native, less community support
|
||||
- Why rejected: NgRx has better Angular integration
|
||||
```
|
||||
|
||||
## ADR Naming Convention
|
||||
|
||||
```
|
||||
docs/adr/
|
||||
├── 0000-adr-template.md # Template file
|
||||
├── 0001-use-nx-monorepo.md
|
||||
├── 0002-adopt-ngrx-signal-store.md
|
||||
├── 0003-standalone-components.md
|
||||
└── README.md # Index of all ADRs
|
||||
```
|
||||
|
||||
## ADR Index Template
|
||||
|
||||
```markdown
|
||||
# Architecture Decision Records
|
||||
|
||||
This directory contains Architecture Decision Records (ADRs) for the ISA Frontend.
|
||||
|
||||
## Index
|
||||
|
||||
| ADR | Title | Status | Date |
|
||||
|-----|-------|--------|------|
|
||||
| [0001](0001-use-nx-monorepo.md) | Use Nx Monorepo | Accepted | 2024-01-15 |
|
||||
| [0002](0002-adopt-ngrx-signal-store.md) | Adopt NgRx Signal Store | Accepted | 2024-03-01 |
|
||||
| [0003](0003-standalone-components.md) | Migrate to Standalone Components | Accepted | 2024-04-01 |
|
||||
|
||||
## Process
|
||||
|
||||
1. Copy `0000-adr-template.md` to `XXXX-short-title.md`
|
||||
2. Fill in the template
|
||||
3. Submit PR for review
|
||||
4. Update status once decided
|
||||
5. Update this index
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One decision per ADR** - Keep ADRs focused
|
||||
2. **Number sequentially** - Never reuse numbers
|
||||
3. **Record context** - Why was this needed?
|
||||
4. **Document alternatives** - Show what was considered
|
||||
5. **Keep concise** - 1-2 pages max
|
||||
6. **Update status** - Mark deprecated decisions
|
||||
7. **Link related ADRs** - Reference superseding decisions
|
||||
8. **Review regularly** - Quarterly ADR review meetings
|
||||
|
||||
## When to Write an ADR
|
||||
|
||||
Write an ADR when:
|
||||
- Choosing a framework or library
|
||||
- Defining code organization patterns
|
||||
- Setting up infrastructure
|
||||
- Establishing conventions
|
||||
- Making trade-offs that affect multiple teams
|
||||
|
||||
Don't write an ADR for:
|
||||
- Small implementation details
|
||||
- Obvious choices with no alternatives
|
||||
- Temporary solutions
|
||||
268
.claude/skills/architecture-documentation/references/arc42.md
Normal file
268
.claude/skills/architecture-documentation/references/arc42.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Arc42 Architecture Documentation Template
|
||||
|
||||
## Overview
|
||||
|
||||
Arc42 is a template for architecture documentation with 12 sections covering all aspects of software architecture.
|
||||
|
||||
## Template Structure
|
||||
|
||||
### 1. Introduction and Goals
|
||||
|
||||
```markdown
|
||||
# 1. Introduction and Goals
|
||||
|
||||
## 1.1 Requirements Overview
|
||||
- Core business requirements driving the architecture
|
||||
- Key functional requirements
|
||||
- Quality goals and priorities
|
||||
|
||||
## 1.2 Quality Goals
|
||||
| Priority | Quality Goal | Description |
|
||||
|----------|-------------|-------------|
|
||||
| 1 | Performance | < 200ms response time |
|
||||
| 2 | Usability | Intuitive for store employees |
|
||||
| 3 | Reliability | 99.9% uptime during store hours |
|
||||
|
||||
## 1.3 Stakeholders
|
||||
| Role | Expectations |
|
||||
|------|-------------|
|
||||
| Store Employee | Fast, reliable daily operations |
|
||||
| IT Operations | Easy deployment and monitoring |
|
||||
| Development Team | Maintainable, testable code |
|
||||
```
|
||||
|
||||
### 2. Architecture Constraints
|
||||
|
||||
```markdown
|
||||
# 2. Architecture Constraints
|
||||
|
||||
## 2.1 Technical Constraints
|
||||
| Constraint | Background |
|
||||
|------------|------------|
|
||||
| Angular 20+ | Company standard frontend framework |
|
||||
| TypeScript strict | Type safety requirement |
|
||||
| Browser support | Chrome 90+, Edge 90+ |
|
||||
|
||||
## 2.2 Organizational Constraints
|
||||
| Constraint | Background |
|
||||
|------------|------------|
|
||||
| Monorepo | Nx-based shared codebase |
|
||||
| CI/CD | Azure DevOps pipelines |
|
||||
| Code review | All changes require PR approval |
|
||||
|
||||
## 2.3 Conventions
|
||||
- Conventional commits
|
||||
- ESLint/Prettier formatting
|
||||
- Component-driven development
|
||||
```
|
||||
|
||||
### 3. System Scope and Context
|
||||
|
||||
```markdown
|
||||
# 3. System Scope and Context
|
||||
|
||||
## 3.1 Business Context
|
||||
[C4 Level 1 - System Context Diagram]
|
||||
|
||||
| Neighbor | Description |
|
||||
|----------|-------------|
|
||||
| Store Employee | Primary user performing daily operations |
|
||||
| Backend APIs | Provides business logic and data |
|
||||
| Printer Service | Label and receipt printing |
|
||||
|
||||
## 3.2 Technical Context
|
||||
[Deployment/Network Diagram]
|
||||
|
||||
| Interface | Protocol | Description |
|
||||
|-----------|----------|-------------|
|
||||
| REST API | HTTPS/JSON | Backend communication |
|
||||
| WebSocket | WSS | Real-time updates |
|
||||
| OAuth2 | HTTPS | Authentication |
|
||||
```
|
||||
|
||||
### 4. Solution Strategy
|
||||
|
||||
```markdown
|
||||
# 4. Solution Strategy
|
||||
|
||||
## Key Architectural Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Angular SPA | Rich interactive UI, offline capability |
|
||||
| NgRx Signal Store | Predictable state management |
|
||||
| Nx Monorepo | Code sharing, consistent tooling |
|
||||
| Standalone Components | Better tree-shaking, simpler imports |
|
||||
|
||||
## Quality Achievement Strategies
|
||||
|
||||
| Quality Goal | Approach |
|
||||
|--------------|----------|
|
||||
| Performance | Lazy loading, caching, code splitting |
|
||||
| Maintainability | Domain-driven library structure |
|
||||
| Testability | Component isolation, dependency injection |
|
||||
```
|
||||
|
||||
### 5. Building Block View
|
||||
|
||||
```markdown
|
||||
# 5. Building Block View
|
||||
|
||||
## Level 1: Application Overview
|
||||
[C4 Container Diagram]
|
||||
|
||||
## Level 2: Domain Decomposition
|
||||
| Domain | Purpose | Libraries |
|
||||
|--------|---------|-----------|
|
||||
| CRM | Customer management | crm-feature-*, crm-data-access-* |
|
||||
| OMS | Order management | oms-feature-*, oms-data-access-* |
|
||||
| Checkout | Transactions | checkout-feature-*, checkout-data-access-* |
|
||||
|
||||
## Level 3: Feature Details
|
||||
[C4 Component Diagrams per domain]
|
||||
```
|
||||
|
||||
### 6. Runtime View
|
||||
|
||||
```markdown
|
||||
# 6. Runtime View
|
||||
|
||||
## Scenario 1: User Login
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
User->>App: Open application
|
||||
App->>Auth: Redirect to login
|
||||
Auth->>App: Return token
|
||||
App->>API: Fetch user profile
|
||||
API->>App: User data
|
||||
App->>User: Display dashboard
|
||||
```
|
||||
|
||||
## Scenario 2: Order Processing
|
||||
[Sequence diagram for order flow]
|
||||
```
|
||||
|
||||
### 7. Deployment View
|
||||
|
||||
```markdown
|
||||
# 7. Deployment View
|
||||
|
||||
## Infrastructure
|
||||
```mermaid
|
||||
graph TD
|
||||
CDN[CDN] --> Browser[User Browser]
|
||||
Browser --> LB[Load Balancer]
|
||||
LB --> API[API Gateway]
|
||||
API --> Services[Backend Services]
|
||||
```
|
||||
|
||||
## Environments
|
||||
| Environment | URL | Purpose |
|
||||
|-------------|-----|---------|
|
||||
| Development | dev.isa.local | Local development |
|
||||
| Staging | staging.isa.com | Integration testing |
|
||||
| Production | isa.com | Live system |
|
||||
```
|
||||
|
||||
### 8. Cross-cutting Concepts
|
||||
|
||||
```markdown
|
||||
# 8. Cross-cutting Concepts
|
||||
|
||||
## 8.1 Domain Model
|
||||
[Domain entity relationships]
|
||||
|
||||
## 8.2 Security
|
||||
- Authentication: OAuth2/OIDC
|
||||
- Authorization: Role-based access control
|
||||
- Data protection: HTTPS, encrypted storage
|
||||
|
||||
## 8.3 Error Handling
|
||||
- Global error interceptor
|
||||
- User-friendly error messages
|
||||
- Error logging to backend
|
||||
|
||||
## 8.4 Logging
|
||||
- @isa/core/logging library
|
||||
- Structured log format
|
||||
- Log levels: trace, debug, info, warn, error
|
||||
```
|
||||
|
||||
### 9. Architecture Decisions
|
||||
|
||||
```markdown
|
||||
# 9. Architecture Decisions
|
||||
|
||||
See [ADR folder](../adr/) for detailed decision records.
|
||||
|
||||
## Key Decisions
|
||||
- ADR-0001: Use Nx Monorepo
|
||||
- ADR-0002: Adopt NgRx Signal Store
|
||||
- ADR-0003: Migrate to Standalone Components
|
||||
```
|
||||
|
||||
### 10. Quality Requirements
|
||||
|
||||
```markdown
|
||||
# 10. Quality Requirements
|
||||
|
||||
## Quality Tree
|
||||
```
|
||||
Quality
|
||||
├── Performance
|
||||
│ ├── Response Time < 200ms
|
||||
│ └── Time to Interactive < 3s
|
||||
├── Reliability
|
||||
│ ├── Uptime 99.9%
|
||||
│ └── Graceful degradation
|
||||
└── Maintainability
|
||||
├── Test coverage > 80%
|
||||
└── Clear module boundaries
|
||||
```
|
||||
|
||||
## Quality Scenarios
|
||||
| Scenario | Measure | Target |
|
||||
|----------|---------|--------|
|
||||
| Page load | Time to interactive | < 3s |
|
||||
| API call | Response time | < 200ms |
|
||||
| Build | CI pipeline duration | < 10min |
|
||||
```
|
||||
|
||||
### 11. Risks and Technical Debt
|
||||
|
||||
```markdown
|
||||
# 11. Risks and Technical Debt
|
||||
|
||||
## Identified Risks
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|-------------|--------|------------|
|
||||
| Backend unavailable | Medium | High | Offline mode |
|
||||
| Performance degradation | Low | Medium | Monitoring |
|
||||
|
||||
## Technical Debt
|
||||
| Item | Priority | Effort |
|
||||
|------|----------|--------|
|
||||
| Legacy Jest tests | Medium | High |
|
||||
| Any types in codebase | High | Medium |
|
||||
```
|
||||
|
||||
### 12. Glossary
|
||||
|
||||
```markdown
|
||||
# 12. Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|------|------------|
|
||||
| ADR | Architecture Decision Record |
|
||||
| C4 | Context, Container, Component, Code model |
|
||||
| ISA | In-Store Application |
|
||||
| SPA | Single Page Application |
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with sections 1-4** - Goals, constraints, context, strategy
|
||||
2. **Add diagrams to section 5** - Building block views
|
||||
3. **Document decisions in section 9** - Link to ADRs
|
||||
4. **Keep updated** - Review quarterly
|
||||
5. **Use templates** - Consistent formatting
|
||||
163
.claude/skills/architecture-documentation/references/c4-model.md
Normal file
163
.claude/skills/architecture-documentation/references/c4-model.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# C4 Model Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The C4 model provides a way to visualize software architecture at four levels of abstraction:
|
||||
1. **Context** - System landscape
|
||||
2. **Container** - Applications and data stores
|
||||
3. **Component** - Internal structure
|
||||
4. **Code** - Class/module detail (optional)
|
||||
|
||||
## Level 1: System Context Diagram
|
||||
|
||||
Shows the system under design and its relationships with users and external systems.
|
||||
|
||||
### PlantUML Template
|
||||
```plantuml
|
||||
@startuml C4_Context
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
|
||||
|
||||
LAYOUT_WITH_LEGEND()
|
||||
|
||||
title System Context Diagram - ISA Frontend
|
||||
|
||||
Person(user, "Store Employee", "Uses the ISA application")
|
||||
Person(admin, "Administrator", "Manages system configuration")
|
||||
|
||||
System(isa, "ISA Frontend", "Angular application for in-store operations")
|
||||
|
||||
System_Ext(backend, "ISA Backend", "REST API services")
|
||||
System_Ext(auth, "Auth Provider", "Authentication service")
|
||||
System_Ext(printer, "Printer Service", "Receipt/label printing")
|
||||
|
||||
Rel(user, isa, "Uses", "Browser")
|
||||
Rel(admin, isa, "Configures", "Browser")
|
||||
Rel(isa, backend, "API calls", "HTTPS/JSON")
|
||||
Rel(isa, auth, "Authenticates", "OAuth2")
|
||||
Rel(isa, printer, "Prints", "WebSocket")
|
||||
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Key Elements
|
||||
- **Person**: Human users of the system
|
||||
- **System**: The system being documented (highlighted)
|
||||
- **System_Ext**: External systems the system depends on
|
||||
- **Rel**: Relationships between elements
|
||||
|
||||
## Level 2: Container Diagram
|
||||
|
||||
Shows the high-level technology choices and how containers communicate.
|
||||
|
||||
### PlantUML Template
|
||||
```plantuml
|
||||
@startuml C4_Container
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
|
||||
|
||||
LAYOUT_WITH_LEGEND()
|
||||
|
||||
title Container Diagram - ISA Frontend
|
||||
|
||||
Person(user, "Store Employee")
|
||||
|
||||
System_Boundary(isa, "ISA Frontend") {
|
||||
Container(spa, "SPA", "Angular 20", "Single-page application")
|
||||
Container(pwa, "Service Worker", "Workbox", "Offline capability")
|
||||
ContainerDb(storage, "Local Storage", "IndexedDB", "Offline data cache")
|
||||
}
|
||||
|
||||
System_Ext(api, "ISA API Gateway")
|
||||
System_Ext(cdn, "CDN", "Static assets")
|
||||
|
||||
Rel(user, spa, "Uses", "Browser")
|
||||
Rel(spa, pwa, "Registers")
|
||||
Rel(pwa, storage, "Caches data")
|
||||
Rel(spa, api, "API calls", "REST/JSON")
|
||||
Rel(spa, cdn, "Loads assets", "HTTPS")
|
||||
|
||||
@enduml
|
||||
```
|
||||
|
||||
### Container Types
|
||||
- **Container**: Application or service
|
||||
- **ContainerDb**: Database or data store
|
||||
- **ContainerQueue**: Message queue
|
||||
|
||||
## Level 3: Component Diagram
|
||||
|
||||
Shows the internal structure of a container.
|
||||
|
||||
### PlantUML Template
|
||||
```plantuml
|
||||
@startuml C4_Component
|
||||
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
|
||||
|
||||
LAYOUT_WITH_LEGEND()
|
||||
|
||||
title Component Diagram - OMS Feature Module
|
||||
|
||||
Container_Boundary(oms, "OMS Feature") {
|
||||
Component(list, "Order List", "Angular Component", "Displays orders")
|
||||
Component(detail, "Order Detail", "Angular Component", "Order management")
|
||||
Component(store, "Order Store", "NgRx Signal Store", "State management")
|
||||
Component(api, "Order API Service", "Angular Service", "API communication")
|
||||
}
|
||||
|
||||
ContainerDb_Ext(backend, "OMS Backend API")
|
||||
|
||||
Rel(list, store, "Reads state")
|
||||
Rel(detail, store, "Reads/writes state")
|
||||
Rel(store, api, "Fetches data")
|
||||
Rel(api, backend, "HTTP requests")
|
||||
|
||||
@enduml
|
||||
```
|
||||
|
||||
## ISA-Frontend Domain Components
|
||||
|
||||
### Suggested Component Structure
|
||||
|
||||
```
|
||||
libs/[domain]/
|
||||
├── feature/ → Component diagrams
|
||||
│ └── [feature]/
|
||||
├── data-access/ → Store/API components
|
||||
│ └── [store]/
|
||||
├── ui/ → Presentational components
|
||||
│ └── [component]/
|
||||
└── util/ → Utility components
|
||||
└── [util]/
|
||||
```
|
||||
|
||||
### Domain Boundaries
|
||||
- **CRM**: Customer management, loyalty
|
||||
- **OMS**: Order management, returns
|
||||
- **Checkout**: Payment, transactions
|
||||
- **Remission**: Product returns processing
|
||||
- **Catalogue**: Product information
|
||||
|
||||
## Mermaid Alternative
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title System Context - ISA Frontend
|
||||
|
||||
Person(user, "Store Employee", "Daily operations")
|
||||
|
||||
System(isa, "ISA Frontend", "Angular SPA")
|
||||
|
||||
System_Ext(backend, "Backend Services")
|
||||
System_Ext(auth, "Auth Service")
|
||||
|
||||
Rel(user, isa, "Uses")
|
||||
Rel(isa, backend, "API calls")
|
||||
Rel(isa, auth, "Authenticates")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **One diagram per level** - Don't mix abstraction levels
|
||||
2. **Consistent naming** - Use same names across diagrams
|
||||
3. **Show key relationships** - Not every possible connection
|
||||
4. **Include legends** - Explain notation
|
||||
5. **Keep it simple** - 5-20 elements per diagram max
|
||||
Reference in New Issue
Block a user