diff --git a/.claude/commands/create-architecture-documentation.md b/.claude/commands/create-architecture-documentation.md deleted file mode 100644 index d4fc703fb..000000000 --- a/.claude/commands/create-architecture-documentation.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/.claude/skills/architecture-documentation/SKILL.md b/.claude/skills/architecture-documentation/SKILL.md new file mode 100644 index 000000000..dc39d6606 --- /dev/null +++ b/.claude/skills/architecture-documentation/SKILL.md @@ -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 diff --git a/.claude/skills/architecture-documentation/references/adr-template.md b/.claude/skills/architecture-documentation/references/adr-template.md new file mode 100644 index 000000000..eb90b8775 --- /dev/null +++ b/.claude/skills/architecture-documentation/references/adr-template.md @@ -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 diff --git a/.claude/skills/architecture-documentation/references/arc42.md b/.claude/skills/architecture-documentation/references/arc42.md new file mode 100644 index 000000000..ba5a324aa --- /dev/null +++ b/.claude/skills/architecture-documentation/references/arc42.md @@ -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 diff --git a/.claude/skills/architecture-documentation/references/c4-model.md b/.claude/skills/architecture-documentation/references/c4-model.md new file mode 100644 index 000000000..d39fd1843 --- /dev/null +++ b/.claude/skills/architecture-documentation/references/c4-model.md @@ -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