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

```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
<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:
```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)