ISA-Frontend/docs/ARCHITECTURE.md

ISA-Frontend Architecture Documentation

Complete architectural analysis of the ISA-Frontend monorepo with C4 models, dependency analysis, and implementation patterns.

Documentation Files

1. Architecture Analysis (architecture-analysis.md) - 51 KB

Comprehensive architectural overview including:

• Complete project structure analysis
• All 63 libraries organized by domain
• Strict layered dependency model
• Technology stack (Angular 20.3.6, Nx 21.3.2, etc.)
• 6 primary domains (OMS, Remission, Checkout, Catalogue, Availability, CRM)
• Core infrastructure (5 libs), UI components (17 libs), shared components (7 libs)
• Modern architecture patterns (standalone components, NgRx Signals, responsive design)
• Complete C4 Model visualization (Levels 1-4)
• State management patterns with code examples
• Component architecture and dependency enforcement

2. Dependency Hierarchy (dependency-hierarchy.md) - 13 KB

Visual dependency organization:

• Layer-based dependency model (4 levels)
• Complete OMS domain dependency tree
• Remission domain dependency tree
• Checkout domain dependency tree
• Cross-domain dependency matrix
• Import path conventions and examples
• NO circular dependencies guarantee
• Bundle dependency impact analysis
• Development workflow for adding features
• Performance considerations (lazy loading, tree shaking)
• Quick reference lookup table

3. Quick Reference (architecture-quick-reference.md) - 15 KB

Developer quick reference guide:

• Project overview at a glance
• Domain summary with key libraries
• Architecture layers visualization
• State management pattern example
• Component structure template
• Common development patterns (search, dialogs, forms, responsive design)
• Essential command cheatsheet
• File organization by domain
• TypeScript path alias mapping
• Design system utilities (Tailwind ISA-specific)
• Testing approach (Vitest vs Jest)
• Troubleshooting guide
• Performance budgets
• Monorepo statistics

---

Quick Navigation

For Architecture Understanding

Start with architecture-analysis.md → C4 Model section

• Understand the 6 primary domains
• Learn the 4-layer dependency model
• See how all 63 libraries fit together

For Dependency Details

Read dependency-hierarchy.md for:

• How libraries depend on each other
• Where to import from (path aliases)
• Why circular dependencies are prevented
• How to add new features without breaking the graph

For Hands-On Development

Use architecture-quick-reference.md for:

• Quick lookup of library purposes
• Code patterns and examples
• Common commands
• File locations and conventions
• Troubleshooting tips

---

Project Structure Overview

ISA-Frontend (Angular 20.3.6 Monorepo)
├── 63 Libraries organized by domain
│   ├── 6 Primary Domains (OMS, Remission, Checkout, Catalogue, Availability, CRM)
│   ├── 17 UI Component Libraries
│   ├── 7 Shared Component Libraries
│   ├── 5 Core Infrastructure Libraries
│   ├── 3 Common Utility Libraries
│   ├── 3 General Utility Libraries
│   ├── 1 Icon Library
│   └── 10 Auto-generated Swagger API Clients
├── 1 Main Application (isa-app)
└── Strict Layered Architecture (Feature → Shared → Data Access → Infrastructure)

---

Key Architecture Principles

1. Domain-Driven Design

• 6 distinct business domains (OMS, Remission, Checkout, etc.)
• Each domain has data-access, feature, and shared components
• Clear domain boundaries prevent unnecessary coupling

2. Strict Layering

• Feature Layer: Route components, user interaction
• Shared Layer: Reusable UI and domain-specific components
• Data Access Layer: NgRx Signals stores and API services
• Infrastructure Layer: Core, common, and generated APIs

3. No Circular Dependencies

• Enforced by TypeScript path aliases
• Verified by ESLint nx plugin
• Enables scalability and maintainability

4. Modern Angular Patterns

• Standalone Components: All new components (no NgModule)
• Signal-based State: NgRx Signals with functional composition
• Type Safety: TypeScript strict mode + Zod validation
• Responsive Design: Breakpoint service instead of CSS media queries

---

Statistics

Metric	Count
Total Libraries	63
Primary Domains	6
UI Components	17
Feature Components	20
Data Access Stores	6
Core Infrastructure	5
Shared Components	7
Common Utilities	3
General Utilities	3
Generated APIs	10
Lines of Documentation	2,165+

---

Technology Stack

• Framework: Angular 20.3.6
• Build Tool: Nx 21.3.2
• Language: TypeScript 5.8.3
• State Management: NgRx Signals 20.0.0
• Styling: Tailwind CSS 3.4.14 + 7 custom plugins
• Testing: Jest (legacy) + Vitest (modern)
• HTTP Client: HttpClient 20.3.6
• Validation: Zod 3.24.2
• API Generation: ng-swagger-gen 2.3.1
• Authentication: OAuth2/OIDC via angular-oauth2-oidc

---

Development Quick Start

# Install and start
npm install
npm start                              # Runs on https://localhost:4200

# Testing
npm test                              # All libraries
npx nx test [project] --skip-nx-cache  # Specific library (fresh results)

# Building
npm run build                          # Development
npm run build-prod                     # Production

# Regenerate APIs
npm run generate:swagger               # From OpenAPI specs
npm run fix:files:swagger              # Unicode cleanup

# Analysis
npx nx graph                           # Visualize dependencies
npx nx show project [project]          # Show project details

---

Common Patterns

Injecting and Using a Store

export class MyComponent {
  protected store = inject(omsStore);
  
  onSearch(term: string) {
    this.store.searchReceipts(term);
  }
}

Creating a New Feature

1. Create standalone component in [domain]/feature/[feature-name]
2. Import from data-access, shared, and UI libraries via path aliases
3. Inject store directly (don't inject individual services)
4. Use reactive template syntax (@if, @for, @switch)

Adding E2E Attributes

<button 
  data-what="submit"
  data-which="primary-action"
  [attr.data-order-id]="orderId"
>
  Submit
</button>

---

Architecture Decisions

Why NgRx Signals?

• Modern, functional composition
• Signals for reactive properties
• Entity management for normalized state
• Auto-persistence with withStorage()
• Request cancellation support

Why Standalone Components?

• No NgModule boilerplate
• Explicit dependencies (in imports)
• Tree-shakeable code
• Easier testing

Why Path Aliases?

• Prevent relative imports across domains
• Enforce architectural boundaries
• Clear import intent (@isa/domain/layer/feature)
• Enable refactoring safety

Why Strict Layering?

• Prevent circular dependencies
• Enable parallel development
• Facilitate testing
• Support scalability

---

Getting Help

1. Library Documentation: Check /libs/[domain]/[layer]/[feature]/README.md
2. Architecture Details: See the appropriate documentation file above
3. Code Examples: Look for similar implementations in the codebase
4. Nx Visualization: Run npx nx graph to see dependency graph
5. Project Configuration: Review nx.json and tsconfig.base.json

---

Related Documentation

• Library Reference: See /docs/library-reference.md for all 63 libraries
• Testing Guidelines: See /docs/guidelines/testing.md for testing patterns
• Code Review Standards: See /.github/review-instructions.md for review process
• CLAUDE.md: Project-specific conventions and best practices

---

Maintenance

These documentation files are maintained manually. When:

• Adding new libraries: Update library reference and domain counts
• Changing architecture patterns: Update quick reference and analysis
• Adding new domains: Document domain structure and dependencies
• Migrating frameworks: Update testing approach sections

---

Document Generation

To regenerate library reference:

npm run docs:generate

This updates /docs/library-reference.md automatically.

---

Last Updated: 2025-10-29
Angular Version: 20.3.6
Nx Version: 21.3.2
Documentation Format: Markdown (3 comprehensive files)