# 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 ```bash # 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 ```typescript 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 ```html ``` --- ## 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: ```bash 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)