From fd8e0194ac8b2273bf29e9e8f6cab32393d2cca0 Mon Sep 17 00:00:00 2001 From: Lorenz Hilpert Date: Wed, 29 Oct 2025 13:39:14 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=9A=20refactor(skills):=20reorganize?= =?UTF-8?q?=20skill=20structure?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename logging-helper to logging for consistency - Remove git-commit-helper (superseded by /commit command) - Add git-workflow skill for Git Flow operations Co-Authored-By: Claude --- .claude/skills/git-commit-helper/SKILL.md | 203 --- .claude/skills/git-workflow/SKILL.md | 352 ++++++ .../{logging-helper => logging}/SKILL.md | 0 .../{logging-helper => logging}/examples.md | 0 .../{logging-helper => logging}/reference.md | 0 .../troubleshooting.md | 0 docs/ARCHITECTURE.md | 287 +++++ docs/architecture-analysis.md | 1120 +++++++++++++++++ docs/architecture-quick-reference.md | 587 +++++++++ docs/dependency-hierarchy.md | 458 +++++++ 10 files changed, 2804 insertions(+), 203 deletions(-) delete mode 100644 .claude/skills/git-commit-helper/SKILL.md create mode 100644 .claude/skills/git-workflow/SKILL.md rename .claude/skills/{logging-helper => logging}/SKILL.md (100%) rename .claude/skills/{logging-helper => logging}/examples.md (100%) rename .claude/skills/{logging-helper => logging}/reference.md (100%) rename .claude/skills/{logging-helper => logging}/troubleshooting.md (100%) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/architecture-analysis.md create mode 100644 docs/architecture-quick-reference.md create mode 100644 docs/dependency-hierarchy.md diff --git a/.claude/skills/git-commit-helper/SKILL.md b/.claude/skills/git-commit-helper/SKILL.md deleted file mode 100644 index 9f82eeefc..000000000 --- a/.claude/skills/git-commit-helper/SKILL.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -name: Git Commit Helper -description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. ---- - -# Git Commit Helper - -## Quick start - -Analyze staged changes and generate commit message: - -```bash -# View staged changes -git diff --staged - -# Generate commit message based on changes -# (Claude will analyze the diff and suggest a message) -``` - -## Commit message format - -Follow conventional commits format: - -``` -(): - -[optional body] - -[optional footer] -``` - -### Types - -- **feat**: New feature -- **fix**: Bug fix -- **docs**: Documentation changes -- **style**: Code style changes (formatting, missing semicolons) -- **refactor**: Code refactoring -- **test**: Adding or updating tests -- **chore**: Maintenance tasks - -### Examples - -**Feature commit:** -``` -feat(auth): add JWT authentication - -Implement JWT-based authentication system with: -- Login endpoint with token generation -- Token validation middleware -- Refresh token support -``` - -**Bug fix:** -``` -fix(api): handle null values in user profile - -Prevent crashes when user profile fields are null. -Add null checks before accessing nested properties. -``` - -**Refactor:** -``` -refactor(database): simplify query builder - -Extract common query patterns into reusable functions. -Reduce code duplication in database layer. -``` - -## Analyzing changes - -Review what's being committed: - -```bash -# Show files changed -git status - -# Show detailed changes -git diff --staged - -# Show statistics -git diff --staged --stat - -# Show changes for specific file -git diff --staged path/to/file -``` - -## Commit message guidelines - -**DO:** -- Use imperative mood ("add feature" not "added feature") -- Keep first line under 50 characters -- Capitalize first letter -- No period at end of summary -- Explain WHY not just WHAT in body - -**DON'T:** -- Use vague messages like "update" or "fix stuff" -- Include technical implementation details in summary -- Write paragraphs in summary line -- Use past tense - -## Multi-file commits - -When committing multiple related changes: - -``` -refactor(core): restructure authentication module - -- Move auth logic from controllers to service layer -- Extract validation into separate validators -- Update tests to use new structure -- Add integration tests for auth flow - -Breaking change: Auth service now requires config object -``` - -## Scope examples - -**Frontend:** -- `feat(ui): add loading spinner to dashboard` -- `fix(form): validate email format` - -**Backend:** -- `feat(api): add user profile endpoint` -- `fix(db): resolve connection pool leak` - -**Infrastructure:** -- `chore(ci): update Node version to 20` -- `feat(docker): add multi-stage build` - -## Breaking changes - -Indicate breaking changes clearly: - -``` -feat(api)!: restructure API response format - -BREAKING CHANGE: All API responses now follow JSON:API spec - -Previous format: -{ "data": {...}, "status": "ok" } - -New format: -{ "data": {...}, "meta": {...} } - -Migration guide: Update client code to handle new response structure -``` - -## Template workflow - -1. **Review changes**: `git diff --staged` -2. **Identify type**: Is it feat, fix, refactor, etc.? -3. **Determine scope**: What part of the codebase? -4. **Write summary**: Brief, imperative description -5. **Add body**: Explain why and what impact -6. **Note breaking changes**: If applicable - -## Interactive commit helper - -Use `git add -p` for selective staging: - -```bash -# Stage changes interactively -git add -p - -# Review what's staged -git diff --staged - -# Commit with message -git commit -m "type(scope): description" -``` - -## Amending commits - -Fix the last commit message: - -```bash -# Amend commit message only -git commit --amend - -# Amend and add more changes -git add forgotten-file.js -git commit --amend --no-edit -``` - -## Best practices - -1. **Atomic commits** - One logical change per commit -2. **Test before commit** - Ensure code works -3. **Reference issues** - Include issue numbers if applicable -4. **Keep it focused** - Don't mix unrelated changes -5. **Write for humans** - Future you will read this - -## Commit message checklist - -- [ ] Type is appropriate (feat/fix/docs/etc.) -- [ ] Scope is specific and clear -- [ ] Summary is under 50 characters -- [ ] Summary uses imperative mood -- [ ] Body explains WHY not just WHAT -- [ ] Breaking changes are clearly marked -- [ ] Related issue numbers are included diff --git a/.claude/skills/git-workflow/SKILL.md b/.claude/skills/git-workflow/SKILL.md new file mode 100644 index 000000000..1de22296f --- /dev/null +++ b/.claude/skills/git-workflow/SKILL.md @@ -0,0 +1,352 @@ +--- +name: git-workflow +description: Enforces ISA-Frontend project Git workflow conventions including branch naming, conventional commits, and PR creation against develop branch +--- + +# Git Workflow Skill + +Enforces Git workflow conventions specific to the ISA-Frontend project. + +## When to Use + +- Creating new branches for features or bugfixes +- Writing commit messages +- Creating pull requests +- Any Git operations requiring adherence to project conventions + +## Core Principles + +### 1. Default Branch is `develop` (NOT `main`) + +- **All PRs target**: `develop` branch +- **Feature branches from**: `develop` +- **Never push directly to**: `develop` or `main` + +### 2. Branch Naming Convention + +**Format**: `/{task-id}-{short-description}` + +**Types**: +- `feature/` - New features or enhancements +- `bugfix/` - Bug fixes +- `hotfix/` - Emergency production fixes + +**Rules**: +- Use English kebab-case for descriptions +- Start with task/issue ID (e.g., `5391`) +- Keep description concise - shorten if too long +- Use hyphens to separate words + +**Examples**: +```bash +# Good +feature/5391-praemie-checkout-action-card-delivery-order +bugfix/6123-fix-login-redirect-loop +hotfix/7890-critical-payment-error + +# Bad +feature/praemie-checkout # Missing task ID +feature/5391_praemie # Using underscores +feature-5391-very-long-description-that-goes-on-forever # Too long +``` + +### 3. Conventional Commits (WITHOUT Co-Author Tags) + +**Format**: `(): ` + +**Types**: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation only +- `style`: Code style (formatting, missing semicolons) +- `refactor`: Code restructuring without feature changes +- `perf`: Performance improvements +- `test`: Adding or updating tests +- `build`: Build system or dependencies +- `ci`: CI configuration +- `chore`: Maintenance tasks + +**Rules**: +- ❌ **NO** "Generated with Claude Code" tags +- ❌ **NO** "Co-Authored-By: Claude" tags +- ✅ Keep first line under 72 characters +- ✅ Use imperative mood ("add" not "added") +- ✅ Body optional but recommended for complex changes + +**Examples**: +```bash +# Good +feat(checkout): add bonus card selection for delivery orders + +fix(crm): resolve customer search filter reset issue + +refactor(oms): extract return validation logic into service + +# Bad +feat(checkout): add bonus card selection + +Generated with Claude Code +Co-Authored-By: Claude + +# Also bad +Added new feature # Wrong tense +Fix bug # Missing scope +``` + +### 4. Pull Request Creation + +**Target Branch**: Always `develop` + +**PR Title Format**: Same as conventional commit +``` +feat(domain): concise description of changes +``` + +**PR Body Structure**: +```markdown +## Summary +- Brief bullet points of changes + +## Related Tasks +- Closes #{task-id} +- Refs #{related-task} + +## Test Plan +- [ ] Unit tests added/updated +- [ ] E2E attributes added +- [ ] Manual testing completed + +## Breaking Changes +None / List breaking changes + +## Screenshots (if UI changes) +[Add screenshots] +``` + +## Common Workflows + +### Creating a Feature Branch + +```bash +# 1. Update develop +git checkout develop +git pull origin develop + +# 2. Create feature branch +git checkout -b feature/5391-praemie-checkout-action-card + +# 3. Work and commit +git add . +git commit -m "feat(checkout): add primary bonus card selection logic" + +# 4. Push to remote +git push -u origin feature/5391-praemie-checkout-action-card + +# 5. Create PR targeting develop (use gh CLI or web UI) +``` + +### Creating a Bugfix Branch + +```bash +# From develop +git checkout develop +git pull origin develop +git checkout -b bugfix/6123-login-redirect-loop + +# Commit +git commit -m "fix(auth): resolve infinite redirect on logout" +``` + +### Creating a Hotfix Branch + +```bash +# From main (production) +git checkout main +git pull origin main +git checkout -b hotfix/7890-payment-processing-error + +# Commit +git commit -m "fix(checkout): critical payment API timeout handling" + +# Merge to both main and develop +``` + +## Commit Message Guidelines + +### Good Commit Messages + +```bash +feat(crm): add customer loyalty tier calculation + +Implements three-tier loyalty system based on annual spend. +Includes migration for existing customer data. + +Refs #5234 + +--- + +fix(oms): prevent duplicate return submissions + +Adds debouncing to return form submission and validates +against existing returns in the last 60 seconds. + +Closes #5891 + +--- + +refactor(catalogue): extract product search into dedicated service + +Moves search logic from component to ProductSearchService +for better testability and reusability. + +--- + +perf(remission): optimize remission list query with pagination + +Reduces initial load time from 3s to 800ms by implementing +cursor-based pagination. + +Closes #6234 +``` + +### Bad Commit Messages + +```bash +# Too vague +fix: bug fixes + +# Missing scope +feat: new feature + +# Wrong tense +fixed the login issue + +# Including banned tags +feat(checkout): add feature + +Generated with Claude Code +Co-Authored-By: Claude +``` + +## Git Configuration Checks + +### Verify Git Setup + +```bash +# Check current branch +git branch --show-current + +# Verify remote +git remote -v # Should show origin pointing to ISA-Frontend + +# Check for uncommitted changes +git status +``` + +## Common Mistakes to Avoid + +```bash +# ❌ Creating PR against main +gh pr create --base main # WRONG + +# ✅ Always target develop +gh pr create --base develop # CORRECT + +# ❌ Using underscores in branch names +git checkout -b feature/5391_my_feature # WRONG + +# ✅ Use hyphens +git checkout -b feature/5391-my-feature # CORRECT + +# ❌ Adding co-author tags +git commit -m "feat: something + +Co-Authored-By: Claude " # WRONG + +# ✅ Clean commit message +git commit -m "feat(scope): something" # CORRECT + +# ❌ Forgetting task ID in branch name +git checkout -b feature/new-checkout-flow # WRONG + +# ✅ Include task ID +git checkout -b feature/5391-new-checkout-flow # CORRECT +``` + +## Integration with Claude Code + +When Claude Code creates commits or PRs: + +### Commit Creation +```bash +# Claude uses conventional commits WITHOUT attribution +git commit -m "feat(checkout): implement bonus card selection + +Adds logic for selecting primary bonus card during checkout +for delivery orders. Includes validation and error handling. + +Refs #5391" +``` + +### PR Creation +```bash +# Target develop by default +gh pr create --base develop \ + --title "feat(checkout): implement bonus card selection" \ + --body "## Summary +- Add primary bonus card selection logic +- Implement validation for delivery orders +- Add error handling for API failures + +## Related Tasks +- Closes #5391 + +## Test Plan +- [x] Unit tests added +- [x] E2E attributes added +- [x] Manual testing completed" +``` + +## Branch Cleanup + +### After PR Merge +```bash +# Update develop +git checkout develop +git pull origin develop + +# Delete local feature branch +git branch -d feature/5391-praemie-checkout + +# Delete remote branch (usually done by PR merge) +git push origin --delete feature/5391-praemie-checkout +``` + +## Quick Reference + +```bash +# Branch naming +feature/{task-id}-{description} +bugfix/{task-id}-{description} +hotfix/{task-id}-{description} + +# Commit format +(): + +# Common types +feat, fix, docs, style, refactor, perf, test, build, ci, chore + +# PR target +Always: develop (NOT main) + +# Banned in commits +- "Generated with Claude Code" +- "Co-Authored-By: Claude" +- Any AI attribution +``` + +## Resources + +- [Conventional Commits](https://www.conventionalcommits.org/) +- Project PR template: `.github/pull_request_template.md` +- Code review standards: `.github/review-instructions.md` diff --git a/.claude/skills/logging-helper/SKILL.md b/.claude/skills/logging/SKILL.md similarity index 100% rename from .claude/skills/logging-helper/SKILL.md rename to .claude/skills/logging/SKILL.md diff --git a/.claude/skills/logging-helper/examples.md b/.claude/skills/logging/examples.md similarity index 100% rename from .claude/skills/logging-helper/examples.md rename to .claude/skills/logging/examples.md diff --git a/.claude/skills/logging-helper/reference.md b/.claude/skills/logging/reference.md similarity index 100% rename from .claude/skills/logging-helper/reference.md rename to .claude/skills/logging/reference.md diff --git a/.claude/skills/logging-helper/troubleshooting.md b/.claude/skills/logging/troubleshooting.md similarity index 100% rename from .claude/skills/logging-helper/troubleshooting.md rename to .claude/skills/logging/troubleshooting.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 000000000..464df75cf --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,287 @@ +# 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) + diff --git a/docs/architecture-analysis.md b/docs/architecture-analysis.md new file mode 100644 index 000000000..b4954e9a4 --- /dev/null +++ b/docs/architecture-analysis.md @@ -0,0 +1,1120 @@ +# ISA-Frontend Monorepo: Comprehensive Architectural Analysis + +**Document Version:** 1.0 +**Last Updated:** 2025-10-29 +**Monorepo Size:** 63 total libraries + 1 main application +**Angular Version:** 20.3.6 +**Nx Version:** 21.3.2 +**Node.js:** >= 22.12.0, < 23.0.0 +**npm:** >= 11.6.0, < 11.7.0 + +--- + +## Table of Contents + +1. [Project Structure Analysis](#project-structure-analysis) +2. [Dependency Architecture](#dependency-architecture) +3. [Technology Stack](#technology-stack) +4. [Domain Boundaries](#domain-boundaries) +5. [Architecture Patterns](#architecture-patterns) +6. [C4 Model Components](#c4-model-components) + +--- + +## Project Structure Analysis + +### Overall Organization + +The ISA-Frontend is a sophisticated Angular monorepo employing **Domain-Driven Design (DDD)** principles with a strict layered architecture. The project uses Nx workspaces for efficient dependency management and build orchestration. + +``` +ISA-Frontend/ +├── apps/ +│ └── isa-app/ # Main Angular application (only runnable app) +│ └── src/ +│ ├── app/ # Application bootstrap and root routing +│ ├── domain/ # Domain-specific feature implementations +│ ├── page/ # Page-level components +│ ├── modal/ # Modal dialogs +│ ├── adapter/ # External service adapters +│ ├── core/ # App-specific core services +│ ├── shared/ # App-specific shared utilities +│ ├── ui/ # App-specific UI components +│ ├── utils/ # App-specific utilities +│ ├── config/ # Configuration files +│ ├── environments/ # Environment-specific configs +│ └── assets/ # Static assets +│ +├── libs/ # 63 domain-driven libraries +│ ├── core/ # Core infrastructure (5 libs) +│ ├── common/ # Common utilities (3 libs) +│ ├── ui/ # UI component system (17 libs) +│ ├── shared/ # Shared domain components (7 libs) +│ ├── availability/ # Availability domain (1 lib) +│ ├── catalogue/ # Catalogue domain (1 lib) +│ ├── checkout/ # Checkout domain (6 libs) +│ ├── crm/ # CRM domain (1 lib) +│ ├── oms/ # Order Management domain (9 libs) +│ ├── remission/ # Remission domain (8 libs) +│ ├── icons/ # Icon library (1 lib) +│ ├── utils/ # General utilities (3 libs) +│ └── [domain]/ +│ ├── data-access/ # State & API integration +│ ├── feature/ # Feature components +│ ├── shared/ # Domain-specific shared +│ └── utils/ # Domain-specific utilities +│ +├── generated/swagger/ # Auto-generated API clients (10 APIs) +│ ├── availability-api/ +│ ├── cat-search-api/ +│ ├── checkout-api/ +│ ├── crm-api/ +│ ├── eis-api/ +│ ├── inventory-api/ +│ ├── isa-api/ +│ ├── oms-api/ +│ ├── print-api/ +│ └── wws-api/ +│ +├── tools/ # Build scripts and utilities +├── docs/ # Documentation +└── config files # Nx, TypeScript, Prettier configs +``` + +### Library Count by Domain + +| Domain | Count | Libraries | +|--------|-------|-----------| +| **UI Components** | 17 | buttons, carousel, datepicker, dialog, empty-state, expandable, input-controls, item-rows, label, layout, menu, progress-bar, search-bar, skeleton-loader, toolbar, tooltip, bullet-list | +| **OMS (Orders)** | 9 | data-access, feature (return-details, return-process, return-review, return-search, return-summary), shared (product-info, task-list), utils (translation) | +| **Remission (Returns)** | 8 | data-access, feature (remission-list, remission-return-receipt-details, remission-return-receipt-list), shared (product, remission-start-dialog, return-receipt-actions, search-item-to-remit-dialog) | +| **Checkout** | 6 | data-access, feature (reward-catalog, reward-order-confirmation, reward-shopping-cart), shared (product-info, reward-selection-dialog) | +| **Core Infrastructure** | 5 | config, logging, navigation, storage, tabs | +| **Shared Components** | 7 | address, filter, product-format, product-image, product-router-link, quantity-control, scanner | +| **Common Utilities** | 3 | data-access, decorators, print | +| **Utility Libraries** | 3 | ean-validation, scroll-position, z-safe-parse | +| **Specialized Domains** | 4 | availability (1), catalogue (1), crm (1), icons (1) | +| **Generated APIs** | 10 | Auto-generated from Swagger/OpenAPI specs | +| **TOTAL** | **63** | + 1 main application (isa-app) | + +--- + +## Dependency Architecture + +### Layer Model + +The architecture enforces strict unidirectional dependencies following a layered approach: + +``` +┌─────────────────────────────────────────────┐ +│ Feature Layer (Pages) │ +│ [oms-feature-return-search, etc.] │ +└────────────────┬────────────────────────────┘ + │ depends on +┌────────────────▼────────────────────────────┐ +│ Shared/UI Component Layer │ +│ [oms-shared-product-info, etc.] │ +│ [ui-buttons, ui-dialog, etc.] │ +└────────────────┬────────────────────────────┘ + │ depends on +┌────────────────▼────────────────────────────┐ +│ Data Access & State Layer │ +│ [oms-data-access, checkout-data-access] │ +│ (NgRx Signals Stores) │ +└────────────────┬────────────────────────────┘ + │ depends on +┌────────────────▼────────────────────────────┐ +│ Infrastructure/Common Layer │ +│ [generated-swagger, common-data-access] │ +│ [core-logging, core-config, core-storage] │ +└─────────────────────────────────────────────┘ +``` + +### Import Boundaries + +All imports use **path aliases** via TypeScript `tsconfig.base.json`: + +```typescript +// Correct (cross-domain) +import { OrderService } from '@isa/oms/data-access'; +import { CheckoutService } from '@isa/checkout/data-access'; +import { UiButton } from '@isa/ui/buttons'; + +// Correct (within domain) +import { OrderState } from '../data-access/order.store'; + +// INCORRECT (relative imports across domains) +// ❌ import { OrderService } from '../../../oms/data-access'; +``` + +### Path Alias Mapping + +All 63 libraries are mapped via path aliases: + +```json +{ + "paths": { + "@isa/[domain]/[layer]/[feature]": ["libs/[domain]/[layer]/[feature]/src/index.ts"], + "@generated/swagger/[api-name]": ["generated/swagger/[api-name]/src/index.ts"] + } +} +``` + +### Dependency Graph Overview + +**Main Application (isa-app) Dependencies:** +- All 9 OMS libraries +- All 8 Remission libraries +- All 6 Checkout libraries +- Specialized domains: Availability, Catalogue, CRM +- All 17 UI component libraries +- All 7 Shared component libraries +- Core infrastructure: 5 libraries +- Common utilities: 3 libraries +- Generated Swagger APIs: 10 clients +- Utility libraries: 3 libraries + +**Key Observations:** +- No circular dependencies (strict acyclic graph) +- Feature libraries depend on shared/UI components +- Shared/UI libraries depend on data-access or core only +- Data-access libraries may depend on generated Swagger APIs and common utilities +- Core libraries have minimal dependencies (infrastructure only) + +--- + +## Technology Stack + +### Angular & Build Tools + +| Component | Version | Purpose | +|-----------|---------|---------| +| **Angular** | 20.3.6 | Core framework with signals, standalone components | +| **Angular CDK** | 20.2.9 | Component primitives (overlays, focus, platform) | +| **TypeScript** | 5.8.3 | Type safety and modern language features | +| **Nx** | 21.3.2 | Monorepo management and build orchestration | +| **Vite** | 6.3.5 | Fast build tool (for testing) | +| **esbuild** | (via Nx) | Fast JavaScript bundler | + +### State Management + +| Library | Version | Usage | +|---------|---------|-------| +| **NgRx Signals** | 20.0.0 | Primary state management with signal stores | +| **NgRx Entity** | 20.0.0 | Normalized entity state management | +| **NgRx Effects** | 20.0.0 | Side effects handling | +| **NgRx Store DevTools** | 20.0.0 | Redux DevTools integration | + +**State Management Pattern:** +- **signalStore()**: Modern functional signal-based stores +- **withEntities()**: Normalized data with entity adapters +- **withStorage()**: SessionStorage/IDB persistence +- **rxMethod()**: Reactive methods with cancellation support +- **withHooks()**: Lifecycle management and cleanup + +### Testing Frameworks + +| Framework | Status | Count | Usage | +|-----------|--------|-------|-------| +| **Jest** | Legacy | 40 libs (65.6%) | Older libraries (being phased out) | +| **Vitest** | Standard | 21 libs (34.4%) | New libraries (migration target) | +| **Spectator** | Jest only | - | Advanced mocking for Jest | +| **ng-mocks** | Both | - | Angular-specific mocking utilities | +| **Angular Testing Utilities** | Vitest | - | TestBed, ComponentFixture | + +**Testing Strategy:** +- New libraries: Vitest + Angular Testing Utilities +- Legacy libraries: Jest + Spectator +- Migration: Ongoing from Jest to Vitest + +### HTTP & API Integration + +| Library | Version | Purpose | +|---------|---------|---------| +| **HttpClient** | 20.3.6 | Angular HTTP client | +| **ng-swagger-gen** | 2.3.1 | OpenAPI/Swagger code generation | +| **Zod** | 3.24.2 | Runtime schema validation | + +**Generated API Clients (10 total):** +1. `availability-api` - Product availability +2. `cat-search-api` - Catalogue search +3. `checkout-api` - Shopping cart & orders +4. `crm-api` - Customer management +5. `eis-api` - Enterprise Info System +6. `inventory-api` - Inventory management +7. `isa-api` - Main ISA API +8. `oms-api` - Order Management System +9. `print-api` - Print services +10. `wws-api` - Warehouse services + +### Form Handling & Input + +| Library | Version | Purpose | +|---------|---------|---------| +| **@angular/forms** | 20.3.6 | Reactive and template-driven forms | +| **Angular CDK** | 20.2.9 | Form primitives and accessibility | + +### UI & Styling + +| Library | Version | Purpose | +|---------|---------|---------| +| **Tailwind CSS** | 3.4.14 | Utility-first CSS framework | +| **ISA Custom Plugins** | - | 7 custom Tailwind plugins (button, typography, menu, label, input, section, select-bullet) | +| **@angular/animations** | 20.3.6 | Animation framework | + +### Additional Libraries + +| Library | Version | Purpose | +|---------|---------|---------| +| **date-fns** | 4.1.0 | Modern date manipulation | +| **moment** | 2.30.1 | Legacy date library (being replaced by date-fns) | +| **lodash** | 4.17.21 | Utility functions | +| **uuid** | 8.3.2 | UUID generation | +| **RxJS** | 7.8.2 | Reactive programming | +| **@microsoft/signalr** | 8.0.7 | Real-time communication (SignalR) | +| **angular-oauth2-oidc** | 20.0.2 | OAuth2/OIDC authentication | +| **ng2-pdf-viewer** | 10.4.0 | PDF viewing | +| **scandit-web-datacapture** | 6.28.1 | Barcode scanning | +| **ngx-matomo-client** | 8.0.0 | Analytics (Matomo) | + +--- + +## Domain Boundaries + +### Domain 1: Order Management System (OMS) + +**Purpose:** Handle product returns, receipt management, and return workflow processing + +**Libraries (9):** +- `@isa/oms/data-access` - State management for returns/receipts +- `@isa/oms/feature/return-search` - Receipt search & filtering +- `@isa/oms/feature/return-details` - Receipt detail view & item selection +- `@isa/oms/feature/return-process` - Return workflow with questions +- `@isa/oms/feature/return-summary` - Return confirmation & printing +- `@isa/oms/feature/return-review` - Return completion review +- `@isa/oms/shared/product-info` - Product display components +- `@isa/oms/shared/task-list` - Receipt task management +- `@isa/oms/utils/translation` - Receipt type translations + +**Key Workflows:** +1. Search for receipts by order ID, EAN, or date range +2. Select items from receipt for return +3. Configure return quantities and categories +4. Answer dynamic return process questions +5. Review and confirm return +6. Print return receipt + +**API Dependencies:** +- `oms-api` - Main OMS API +- `isa-api` - General ISA API +- `print-api` - Receipt printing + +**State Management:** +- NgRx Signal Store with entity normalization +- Session persistence for in-progress returns + +--- + +### Domain 2: Remission (Returns Management) + +**Purpose:** Manage warehouse remission processes (mandatory and department returns) + +**Libraries (8):** +- `@isa/remission/data-access` - Remission state and API +- `@isa/remission/feature/remission-list` - Main remission list view +- `@isa/remission/feature/remission-return-receipt-list` - Return receipts view +- `@isa/remission/feature/remission-return-receipt-details` - Receipt details +- `@isa/remission/shared/product` - Product components +- `@isa/remission/shared/remission-start-dialog` - Start remission workflow +- `@isa/remission/shared/return-receipt-actions` - Receipt action buttons +- `@isa/remission/shared/search-item-to-remit-dialog` - Item search dialog + +**Key Workflows:** +1. View mandatory (Pflicht) vs department (Abteilung) remissions +2. Create return receipts ("Warenbegleitschein") +3. Assign package numbers +4. Search and add items to remission +5. Complete remission items +6. Delete/continue remission + +**API Dependencies:** +- Remission-specific APIs via ISA backend + +--- + +### Domain 3: Checkout & Rewards + +**Purpose:** Shopping cart, order placement, and loyalty rewards redemption + +**Libraries (6):** +- `@isa/checkout/data-access` - Cart and checkout state +- `@isa/checkout/feature/reward-catalog` - Reward item browsing +- `@isa/checkout/feature/reward-shopping-cart` - Cart with rewards +- `@isa/checkout/feature/reward-order-confirmation` - Order confirmation +- `@isa/checkout/shared/product-info` - Product display +- `@isa/checkout/shared/reward-selection-dialog` - Reward selection UI + +**Key Workflows:** +1. Add items to shopping cart +2. View cart items and totals +3. Redeem loyalty points for rewards +4. Browse available rewards +5. Place order with rewards +6. View order confirmation + +**API Dependencies:** +- `checkout-api` - Cart and order APIs +- `crm-api` - Customer and bonus card info + +**State Management:** +- NgRx Signal Store for cart/checkout state +- Reward selection dialog state + +--- + +### Domain 4: Catalogue + +**Purpose:** Product search and catalogue management + +**Libraries (1):** +- `@isa/catalogue/data-access` - Catalogue search and filtering + +**Key Capabilities:** +- Product search by EAN, title, author +- Loyalty program integration +- Format and edition handling +- Stock availability by location + +**API Dependencies:** +- `cat-search-api` - Catalogue search +- `availability-api` - Stock availability + +--- + +### Domain 5: Availability + +**Purpose:** Product stock availability across retail locations + +**Libraries (1):** +- `@isa/availability/data-access` - Availability queries + +**Key Capabilities:** +- Check stock by location +- Support multiple order types +- Delivery method validation + +**API Dependencies:** +- `availability-api` - Availability service + +--- + +### Domain 6: CRM (Customer Relationship Management) + +**Purpose:** Customer data, addresses, and bonus card management + +**Libraries (1):** +- `@isa/crm/data-access` - Customer, address, and bonus card state + +**Key Capabilities:** +- Customer lookup and management +- Shipping address management +- Payer information +- Bonus card (Prämienkarte) status and points + +**API Dependencies:** +- `crm-api` - Customer management + +--- + +### Shared Component Domains + +#### UI Component Library (17 libraries) + +Universal design system components used across all domains: + +| Component | Purpose | +|-----------|---------| +| `ui-buttons` | Button variants (primary, secondary, ghost, etc.) | +| `ui-input-controls` | Form inputs, checkboxes, radio buttons | +| `ui-dialog` | Modal dialogs and alert boxes | +| `ui-datepicker` | Date range picker | +| `ui-layout` | Responsive layout utilities and breakpoint service | +| `ui-menu` | Dropdown menus | +| `ui-toolbar` | Top bar container | +| `ui-search-bar` | Search input with autocomplete | +| `ui-expandable` | Expandable/collapsible sections | +| `ui-empty-state` | Empty state messages | +| `ui-skeleton-loader` | Loading placeholders | +| `ui-carousel` | Horizontal scroll container | +| `ui-item-rows` | Data row display | +| `ui-progress-bar` | Progress indication | +| `ui-tooltip` | Tooltip overlays | +| `ui-label` | Tag/label components | +| `ui-bullet-list` | Bullet point lists | + +**Design System Features:** +- Tailwind CSS + 7 custom plugins +- Custom breakpoints: Tablet, Desktop, DesktopL, DesktopXL +- ISA brand color palette (isa-accent-*, isa-text-*) +- Typography system (14 custom utilities) +- Consistent spacing and sizing + +#### Shared Components (7 libraries) + +Domain-agnostic components for product display and interaction: + +| Component | Purpose | +|-----------|---------| +| `shared-address` | Address display (multi-line, inline) | +| `shared-filter` | Filter and search UI | +| `shared-product-image` | Product image with CDN support | +| `shared-product-format` | Format display (hardcover, audiobook, etc.) | +| `shared-product-router-link` | Product navigation links | +| `shared-quantity-control` | Quantity selector | +| `shared-scanner` | Barcode scanner interface | + +--- + +### Core Infrastructure Libraries (5) + +#### `@isa/core/config` +- Type-safe configuration management +- Runtime validation +- Nested object access + +#### `@isa/core/logging` +- Structured logging with log levels +- Multiple output sinks (console, remote) +- Hierarchical context support +- Performance optimized + +#### `@isa/core/navigation` +- Context preservation for multi-step flows +- Tab-scoped temporary state storage +- Return URL management +- Wizard state preservation + +#### `@isa/core/storage` +- Type-safe storage abstraction +- NgRx Signals integration +- Multiple backends: localStorage, sessionStorage, IndexedDB +- Server-side user state sync + +#### `@isa/core/tabs` +- Browser-like tab management +- Multi-tab navigation +- History tracking +- Intelligent persistence + +--- + +### Common Utilities (3) + +#### `@isa/common/data-access` +- Core data fetching patterns +- RxJS operator library +- Error handling and response models +- Request batching infrastructure + +#### `@isa/common/decorators` +- Method validation decorators +- Caching and debouncing +- Rate limiting +- Enhanced logging decorators + +#### `@isa/common/print` +- Printer discovery and selection +- Print queue management +- Label and office printer support + +--- + +### Utility Libraries (3) + +| Utility | Purpose | +|---------|---------| +| `@isa/utils/ean-validation` | EAN barcode validation with reactive forms | +| `@isa/utils/scroll-position` | Scroll position preservation | +| `@isa/utils/z-safe-parse` | Safe Zod parsing with fallbacks | + +--- + +## Architecture Patterns + +### 1. Feature-Based Organization + +Each domain follows a **feature-based** organization: + +``` +libs/[domain]/ +├── data-access/ # State store + API services +├── feature/ # Feature components (pages/views) +│ ├── feature-1/ +│ ├── feature-2/ +│ └── ... +├── shared/ # Domain-specific reusable components +└── utils/ # Domain-specific utilities +``` + +**Benefits:** +- Clear domain boundaries +- Easy to scale and maintain +- Explicit dependencies +- Parallel team development + +### 2. Standalone Components + +All new components use Angular's **standalone** architecture: + +```typescript +@Component({ + selector: 'oms-return-details', + standalone: true, + imports: [CommonModule, OmsSharedModule, UiButtonsModule], + template: `...`, +}) +export class OmsReturnDetailsComponent {} +``` + +**Advantages:** +- Explicit dependencies in imports +- Tree-shakeable +- Easier to test +- No NgModule boilerplate + +### 3. Signal-Based State Management + +Uses modern **NgRx Signals** with functional composition: + +```typescript +export const orderStore = signalStore( + withState({ orders: [] as Order[] }), + withEntities({ entity: type() }), + withMethods((store) => ({ + loadOrders: rxMethod( + pipe( + switchMap(() => api.getOrders()), + tapResponse( + (orders) => patchState(store, setAllEntities(orders)), + (error) => handleError(error) + ) + ) + ), + })), + withStorage({ key: 'orders' }) // Session persistence +); +``` + +**Features:** +- Signals for reactive state +- Entity management for normalized data +- Request cancellation via `rxMethod()` +- Automatic persistence +- Type-safe + +### 4. Data Access Layer Pattern + +Each domain has a dedicated data-access library: + +```typescript +// Service wrapping generated API +export class OmsApiService { + private api = inject(OmsApi); + + getReceipt(id: string): Observable { + return this.api.getReceipt(id).pipe( + tapResponse( + (receipt) => Receipt.parse(receipt), // Zod validation + (error) => this.handleError(error) + ) + ); + } +} + +// Domain store +export const omsStore = signalStore( + withEntities({ entity: type() }), + withMethods((store, api = inject(OmsApiService)) => ({ + load: rxMethod( + pipe( + switchMap((id) => api.getReceipt(id)), + tapResponse( + (receipt) => patchState(store, addEntity(receipt)) + ) + ) + ), + })) +); +``` + +### 5. Responsive Design with Breakpoint Service + +Uses **breakpoint service** instead of CSS-only solutions: + +```typescript +import { breakpoint, Breakpoint } from '@isa/ui/layout'; + +@Component({ + template: ` + @if (isDesktop()) { + + } @else { + + } + `, +}) +export class ResponsiveComponent { + isDesktop = breakpoint([ + Breakpoint.Desktop, + Breakpoint.DesktopL, + Breakpoint.DesktopXL + ]); +} +``` + +**Available Breakpoints:** +- Tablet: max-width 1279px +- Desktop: 1280px - 1439px +- DesktopL: 1440px - 1919px +- DesktopXL: 1920px+ + +### 6. Error Handling & Validation + +Two-tier approach with TypeScript + Zod: + +```typescript +import { z } from 'zod'; + +// Schema definition +const OrderSchema = z.object({ + id: z.string().uuid(), + items: z.array(OrderItemSchema), + total: z.number().positive(), +}); + +type Order = z.infer; + +// Usage +function processOrder(data: unknown): Result { + return OrderSchema.safeParse(data); +} +``` + +### 7. Request Cancellation + +Built-in cancellation support via custom RxJS operators: + +```typescript +export class ReturnSearchComponent { + private searchTerm$ = new Subject(); + + search$ = this.searchTerm$.pipe( + debounceTime(300), + distinctUntilChanged(), + takeUntilKeydown('Escape'), // Cancel on ESC + switchMap((term) => this.api.search(term)) + ); +} +``` + +**Custom Operators:** +- `takeUntilAborted()` - Abort signal support +- `takeUntilKeydown()` - Keyboard event cancellation +- `takeUntilKeydownEscape()` - Escape key shortcut + +--- + +## C4 Model Components + +### C4 Level 1: System Context + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ISA Frontend │ +│ (Angular 20.3.6 Monorepo - Order/Returns Management) │ +│ - OMS (Order Management) │ +│ - Remission (Returns Processing) │ +│ - Checkout (Shopping Cart & Rewards) │ +│ - Catalogue (Product Search) │ +│ - CRM (Customer Management) │ +└──────────────┬──────────────────────────────────────────────┘ + │ + ┌────────┼────────┐ + │ │ │ + ▼ ▼ ▼ +┌──────────┐ ┌──────────┐ ┌──────────────┐ +│ Backend │ │Browser/ │ │Native Mobile │ +│ REST API │ │Web App │ │(WebView) │ +└──────────┘ └──────────┘ └──────────────┘ +``` + +### C4 Level 2: Container Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ ISA Frontend Application │ +│ (Angular 20.3.6 SPA + PWA) │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Routing & Shell │ │ +│ │ - isa-app root │ │ +│ │ - Tab navigation (5+ open tabs) │ │ +│ │ - Auth flow │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼──────────────────────────────┐ │ +│ │ Domain Feature Modules │ │ +│ │ ┌────────────────────────────────────────────┐ │ │ +│ │ │ OMS (Return Management) │ │ │ +│ │ │ - Search → Details → Process → Review │ │ │ +│ │ └────────────────────────────────────────────┘ │ │ +│ │ ┌────────────────────────────────────────────┐ │ │ +│ │ │ Remission (Warehouse Returns) │ │ │ +│ │ │ - List → Receipt → Actions │ │ │ +│ │ └────────────────────────────────────────────┘ │ │ +│ │ ┌────────────────────────────────────────────┐ │ │ +│ │ │ Checkout (Orders & Rewards) │ │ │ +│ │ │ - Cart → Rewards → Confirmation │ │ │ +│ │ └────────────────────────────────────────────┘ │ │ +│ │ ┌────────────────────────────────────────────┐ │ │ +│ │ │ Catalogue (Product Search) │ │ │ +│ │ │ - Search → Browse → Details │ │ │ +│ │ └────────────────────────────────────────────┘ │ │ +│ │ ┌────────────────────────────────────────────┐ │ │ +│ │ │ CRM (Customer Management) │ │ │ +│ │ │ - Customer → Address → Bonus Card │ │ │ +│ │ └────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼──────────────────────────────┐ │ +│ │ Shared Component Layer │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ UI Component Library (17 libs) │ │ │ +│ │ │ Buttons, Forms, Dialogs, etc. │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Shared Components (7 libs) │ │ │ +│ │ │ Product Info, Address, Scanner, etc. │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼──────────────────────────────┐ │ +│ │ Data Access & State Layer │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Domain Stores (NgRx Signals) │ │ │ +│ │ │ - Order Store │ │ │ +│ │ │ - Remission Store │ │ │ +│ │ │ - Checkout Store │ │ │ +│ │ │ - Catalogue Store │ │ │ +│ │ │ - CRM Store │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Data Access Services │ │ │ +│ │ │ (wrapping generated APIs) │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────▼──────────────────────────────┐ │ +│ │ Infrastructure & Core Layer │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Core Services (5 libs) │ │ │ +│ │ │ - Config (runtime settings) │ │ │ +│ │ │ - Logging (structured logging) │ │ │ +│ │ │ - Navigation (context preservation) │ │ │ +│ │ │ - Storage (localStorage/IDB) │ │ │ +│ │ │ - Tabs (multi-tab management) │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Common Services (3 libs) │ │ │ +│ │ │ - Data Access (batching, operators) │ │ │ +│ │ │ - Decorators (caching, validation) │ │ │ +│ │ │ - Print (printer management) │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────┐ │ │ +│ │ │ Generated Swagger API Clients (10) │ │ │ +│ │ │ - oms-api, checkout-api, crm-api, etc. │ │ │ +│ │ └──────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────┘ + │ + │ HTTP/WebSocket + │ + ▼ +┌──────────────────────────────────────────────────┐ +│ Backend Services (REST + SignalR) │ +├──────────────────────────────────────────────────┤ +│ - ISA API (core business logic) │ +│ - OMS API (order management) │ +│ - Remission API (returns processing) │ +│ - Checkout API (shopping cart) │ +│ - CRM API (customer data) │ +│ - Catalogue API (product search) │ +│ - Availability API (stock checking) │ +│ - Print API (label printing) │ +│ - EIS API (enterprise info system) │ +│ - WWS API (warehouse services) │ +└──────────────────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────┐ +│ External Services │ +├──────────────────────────────────────────────────┤ +│ - Database (SQL Server) │ +│ - File Storage (CDN for product images) │ +│ - Print Queue (label/office printers) │ +│ - Barcode Scanner (Scandit SDK) │ +│ - Analytics (Matomo) │ +│ - OAuth/OIDC (authentication) │ +└──────────────────────────────────────────────────┘ +``` + +### C4 Level 3: Component Structure (OMS Domain Example) + +``` +┌──────────────────────────────────────────────────────────────┐ +│ OMS Domain (Order Management System) │ +│ (9 Libraries) │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ Feature Components (Route-Level) │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-feature-return-search │ │ │ +│ │ │ - Search for receipts (EAN, order ID, date) │ │ │ +│ │ │ - Filter and pagination │ │ │ +│ │ │ - Imports: shared/product-info, ui/buttons │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-feature-return-details │ │ │ +│ │ │ - View receipt items │ │ │ +│ │ │ - Select items for return │ │ │ +│ │ │ - Configure quantities and categories │ │ │ +│ │ │ - Imports: shared/product-info, ui/* │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-feature-return-process │ │ │ +│ │ │ - Dynamic return reason questions │ │ │ +│ │ │ - Validation and backend integration │ │ │ +│ │ │ - Imports: data-access, ui/input-controls │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-feature-return-summary │ │ │ +│ │ │ - Review all return details │ │ │ +│ │ │ - Confirm and submit │ │ │ +│ │ │ - Trigger receipt printing │ │ │ +│ │ │ - Imports: data-access, shared/*, ui/* │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-feature-return-review │ │ │ +│ │ │ - View completed return confirmation │ │ │ +│ │ │ - Display return receipt │ │ │ +│ │ │ - Option to reprint │ │ │ +│ │ │ - Imports: data-access, shared/* │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────────▼────────────────────────────────┐ │ +│ │ Shared Components (Reusable UI) │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-shared-product-info │ │ │ +│ │ │ - Product row display │ │ │ +│ │ │ - EAN, title, author, format, stock info │ │ │ +│ │ │ - Imports: shared/product-*, ui/item-rows │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-shared-task-list │ │ │ +│ │ │ - Display return tasks │ │ │ +│ │ │ - Mark complete/incomplete │ │ │ +│ │ │ - Imports: ui/expandable, ui/item-rows │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────────▼────────────────────────────────┐ │ +│ │ Data Access Layer │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-data-access │ │ │ +│ │ │ │ │ │ +│ │ │ NgRx Signal Stores: │ │ │ +│ │ │ - receiptStore (list, details, filters) │ │ │ +│ │ │ - returnStore (current return process) │ │ │ +│ │ │ - questionStore (dynamic questions) │ │ │ +│ │ │ │ │ │ +│ │ │ Services: │ │ │ +│ │ │ - OmsReceiptService (API wrapper) │ │ │ +│ │ │ - OmsReturnService (return workflow) │ │ │ +│ │ │ - PrintService (receipt printing) │ │ │ +│ │ │ │ │ │ +│ │ │ Imports: @generated/swagger/oms-api │ │ │ +│ │ │ @generated/swagger/print-api │ │ │ +│ │ │ @isa/core/logging │ │ │ +│ │ │ @isa/common/data-access │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌────────────────────────▼────────────────────────────────┐ │ +│ │ Utilities │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ oms-utils-translation │ │ │ +│ │ │ - Receipt type translations (Rechnung, etc.) │ │ │ +│ │ │ - Service and pipe for formatting │ │ │ +│ │ └──────────────────────────────────────────────────┘ │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ │ +└──────────────────────────┬───────────────────────────────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ OMS API │ │ Print API │ │ ISA API │ +│ │ │ │ │ │ +│ - getReceipt │ │ - printLabel │ │ - createReturn +│ - listReceipts +│ - createReturn +└──────────────┘ └──────────────┘ └──────────────┘ +``` + +### C4 Level 4: Code Structure (Single Component) + +```typescript +// File: libs/oms/feature/return-search/src/return-search.component.ts + +import { Component, OnInit, inject } from '@angular/core'; +import { CommonModule } from '@angular/common'; +import { ReactiveFormsModule } from '@angular/forms'; + +// Feature dependencies +import { OmsStore, omsStore } from '@isa/oms/data-access'; + +// Shared components +import { UiSearchBar } from '@isa/ui/search-bar'; +import { UiButton, UiPrimaryButton } from '@isa/ui/buttons'; +import { OmsProductInfoComponent } from '@isa/oms/shared/product-info'; + +// Shared utilities +import { UiEmptyState } from '@isa/ui/empty-state'; + +@Component({ + selector: 'oms-feature-return-search', + standalone: true, + imports: [ + CommonModule, + ReactiveFormsModule, + UiSearchBar, + UiButton, + UiPrimaryButton, + OmsProductInfoComponent, + UiEmptyState, + ], + template: ` +
+ + + @if (store.receipts(); as receipts) { + @if (receipts.length > 0) { +
+ @for (receipt of receipts; track receipt.id) { + + } +
+ } @else { + + } + } +
+ `, +}) +export class OmsReturnSearchComponent implements OnInit { + // Inject the domain store (NgRx Signals) + protected store = inject(omsStore); + + private router = inject(Router); + + ngOnInit() { + // Load receipts on component init + // Store automatically handles state, persistence, etc. + } + + onSearch(term: string) { + this.store.searchReceipts(term); + } +} +``` + +--- + +## Architectural Strengths + +1. **Strong Domain Separation**: Clear boundaries between OMS, Remission, Checkout, etc. +2. **Scalable Structure**: 63 libraries organized by domain and layer +3. **Type Safety**: TypeScript + Zod validation across all APIs +4. **Modern Patterns**: Standalone components, signals, NgRx Signals stores +5. **Code Reuse**: 17 UI component libraries + 7 shared component libraries +6. **Testing Strategy**: Vitest + Jest with clear framework separation +7. **Build Performance**: Nx caching and incremental builds +8. **State Management**: Centralized, persistent, typed NgRx Signals stores +9. **Error Handling**: Global HTTP interceptors and consistent error patterns +10. **Responsive Design**: Breakpoint service for proper mobile/desktop support + +--- + +## Architectural Considerations + +1. **Migration from Jest to Vitest**: Currently 40 Jest libraries, moving to 21 Vitest +2. **Legacy Code**: Some legacy modules still exist alongside new standalone patterns +3. **Bundle Size**: Monitor carefully (2MB warning, 5MB error limits) +4. **Cache Management**: Nx cache can cause issues - use `--skip-nx-cache` for tests +5. **Authentication**: OAuth2/OIDC required for all API calls +6. **Multi-Tab State**: Tab navigation requires careful state management + +--- + +## Key Files for Reference + +- **Architecture Definition**: `/nx.json`, `/tsconfig.base.json` +- **Library Reference**: `/docs/library-reference.md` +- **Testing Guidelines**: `/docs/guidelines/testing.md` +- **App Bootstrap**: `/apps/isa-app/src/app/app.module.ts` +- **Routing**: `/apps/isa-app/src/app/app-routing.module.ts` +- **Configuration**: `/apps/isa-app/src/config/` + +--- + +## Deployment & Build Configuration + +### Development +```bash +npm start # Run with SSL (required for auth flows) +``` + +### Testing +```bash +npm test # All libraries except main app +npm run ci # CI with coverage +npx nx test --skip-nx-cache # Specific project (fresh) +``` + +### Production Build +```bash +npm run build-prod # Production bundle +npx nx build isa-app --configuration=production +``` + +### API Generation +```bash +npm run generate:swagger # Regenerate all 10 Swagger clients +npm run fix:files:swagger # Unicode cleanup post-generation +``` + +### Documentation +```bash +npm run docs:generate # Update library reference +npm run prettier # Format code +``` + diff --git a/docs/architecture-quick-reference.md b/docs/architecture-quick-reference.md new file mode 100644 index 000000000..bd198a68c --- /dev/null +++ b/docs/architecture-quick-reference.md @@ -0,0 +1,587 @@ +# ISA-Frontend Architecture: Quick Reference Guide + +## Project Overview at a Glance + +| Aspect | Details | +|--------|---------| +| **Project Type** | Angular 20.3.6 Monorepo (Domain-Driven Design) | +| **Build Tool** | Nx 21.3.2 | +| **Total Libraries** | 63 (organized by domain + infrastructure) | +| **Main Application** | `isa-app` (only runnable app) | +| **Domains** | OMS, Remission, Checkout, Catalogue, Availability, CRM | +| **UI Components** | 17 specialized design system libraries | +| **Testing** | Jest (legacy) + Vitest (modern) - migration in progress | +| **State Management** | NgRx Signals with entity normalization | +| **API Clients** | 10 auto-generated from Swagger/OpenAPI specs | +| **Styling** | Tailwind CSS + 7 custom plugins | +| **Authentication** | OAuth2/OIDC via `angular-oauth2-oidc` | +| **Barcode Support** | Scandit Web Datacapture | +| **Analytics** | Matomo integration | + +--- + +## Domain Summary + +### 1. Order Management System (OMS) - 9 Libraries +**Focus:** Return workflows and receipt management + +| Library | Purpose | +|---------|---------| +| `oms-data-access` | State + API integration | +| `oms-feature-return-search` | Receipt search interface | +| `oms-feature-return-details` | Item selection & configuration | +| `oms-feature-return-process` | Dynamic return questions | +| `oms-feature-return-summary` | Confirmation & printing | +| `oms-feature-return-review` | Completion review | +| `oms-shared-product-info` | Product display | +| `oms-shared-task-list` | Task management UI | +| `oms-utils-translation` | Receipt type labels | + +**Key APIs:** oms-api, isa-api, print-api + +--- + +### 2. Remission (Returns Management) - 8 Libraries +**Focus:** Warehouse return processing (mandatory + department) + +| Library | Purpose | +|---------|---------| +| `remission-data-access` | State + API integration | +| `remission-feature-remission-list` | Main list view | +| `remission-feature-remission-return-receipt-list` | Receipt list | +| `remission-feature-remission-return-receipt-details` | Receipt details | +| `remission-shared-product` | Product components | +| `remission-shared-remission-start-dialog` | Start workflow | +| `remission-shared-return-receipt-actions` | Action buttons | +| `remission-shared-search-item-to-remit-dialog` | Item search | + +**Key APIs:** Remission-specific via ISA backend + +--- + +### 3. Checkout & Rewards - 6 Libraries +**Focus:** Shopping cart, orders, loyalty rewards + +| Library | Purpose | +|---------|---------| +| `checkout-data-access` | Cart state + API | +| `checkout-feature-reward-catalog` | Reward browsing | +| `checkout-feature-reward-shopping-cart` | Cart with rewards | +| `checkout-feature-reward-order-confirmation` | Order confirmation | +| `checkout-shared-product-info` | Product display | +| `checkout-shared-reward-selection-dialog` | Reward selection | + +**Key APIs:** checkout-api, crm-api (bonus cards) + +--- + +### 4. Catalogue - 1 Library +**Focus:** Product search and discovery + +| Library | Purpose | +|---------|---------| +| `catalogue-data-access` | Search + filtering | + +**Key APIs:** cat-search-api, availability-api + +--- + +### 5. Availability - 1 Library +**Focus:** Product stock checking + +| Library | Purpose | +|---------|---------| +| `availability-data-access` | Stock queries | + +**Key APIs:** availability-api + +--- + +### 6. CRM - 1 Library +**Focus:** Customer data and bonus cards + +| Library | Purpose | +|---------|---------| +| `crm-data-access` | Customer + bonus card state | + +**Key APIs:** crm-api + +--- + +## Architecture Layers + +``` +┌─────────────────────────────────┐ +│ FEATURE LAYER (User-Facing) │ +│ - Components with routes │ +│ - User interactions │ +│ - Navigation handlers │ +└──────────────┬──────────────────┘ + │ imports +┌──────────────▼──────────────────┐ +│ SHARED LAYER (Reusable) │ +│ - UI components (17 libs) │ +│ - Shared components (7 libs) │ +│ - Domain shared │ +└──────────────┬──────────────────┘ + │ imports +┌──────────────▼──────────────────┐ +│ DATA ACCESS LAYER (State) │ +│ - NgRx Signal Stores │ +│ - API Services │ +│ - Entity management │ +└──────────────┬──────────────────┘ + │ imports +┌──────────────▼──────────────────┐ +│ INFRASTRUCTURE (Foundation) │ +│ - Core libraries (5) │ +│ - Common utilities (3) │ +│ - Generated APIs (10) │ +│ - Utilities (3) │ +└─────────────────────────────────┘ +``` + +--- + +## State Management Pattern + +### NgRx Signals Store Structure + +```typescript +export const orderStore = signalStore( + // 1. State definition + withState({ + orders: [] as Order[], + selected: null as Order | null, + loading: false, + error: null as Error | null, + }), + + // 2. Entity management (auto-normalization) + withEntities({ entity: type() }), + + // 3. Computed values + withComputed((store) => ({ + orderCount: computed(() => store.orders().length), + hasSelected: computed(() => store.selected() !== null), + })), + + // 4. Methods for state mutations + withMethods((store, api = inject(OmsApiService)) => ({ + load: rxMethod( + pipe( + tapResponse( + (orders) => patchState(store, setAllEntities(orders)), + (error) => handleError(error) + ) + ) + ), + select: (order: Order) => { + patchState(store, { selected: order }); + }, + })), + + // 5. Auto persistence + withStorage({ key: 'orders' }), + + // 6. Cleanup hooks + withHooks({ + onInit: ({ load }) => load(), + onDestroy: () => console.log('Store destroyed'), + }) +); +``` + +**Key Features:** +- Signals: Reactive properties +- Entity management: Auto-normalized state +- Methods: Encapsulated mutations +- Storage: Automatic persistence +- Hooks: Lifecycle management + +--- + +## Component Structure + +### Standalone Component Example + +```typescript +@Component({ + selector: 'oms-return-search', + standalone: true, + imports: [ + CommonModule, + ReactiveFormsModule, + // Shared components + UiSearchBar, + UiButton, + OmsProductInfo, + UiEmptyState, + ], + template: ` +
+ + + @if (store.receipts(); as receipts) { + @if (receipts.length > 0) { + + } @else { + + } + } @loading { + + } +
+ `, + styles: [`...`], +}) +export class OmsReturnSearchComponent { + protected store = inject(omsStore); + private api = inject(OmsApiService); + + onSearch(term: string) { + this.store.searchReceipts(term); + } +} +``` + +**Best Practices:** +- ✅ Standalone components only +- ✅ Explicit imports +- ✅ Inject store, not services +- ✅ Use store methods directly +- ✅ Let control flow (@if, @for) + +--- + +## Common Patterns + +### 1. Search with Debouncing + +```typescript +export class SearchComponent { + private searchTerm$ = new Subject(); + + results$ = this.searchTerm$.pipe( + debounceTime(300), + distinctUntilChanged(), + switchMap((term) => this.api.search(term)), + takeUntilKeydown('Escape') + ); + + onSearch(term: string) { + this.searchTerm$.next(term); + } +} +``` + +### 2. Modal/Dialog Handling + +```typescript +export class DialogComponent { + private dialog = inject(DialogService); + + openRewardSelection() { + this.dialog.open(RewardSelectionDialog, { + data: { cart: this.cart }, + }).afterClosed$.subscribe((reward) => { + if (reward) { + this.store.selectReward(reward); + } + }); + } +} +``` + +### 3. Form Validation + +```typescript +export class ReturnProcessComponent { + form = new FormGroup({ + reason: new FormControl('', [Validators.required]), + quantity: new FormControl(1, [Validators.min(1)]), + comments: new FormControl(''), + }); + + submit() { + if (this.form.valid) { + this.store.submitReturn(this.form.value); + } + } +} +``` + +### 4. Responsive Design + +```typescript +export class ResponsiveComponent { + // Use breakpoint service instead of CSS-only + isDesktop = breakpoint([ + Breakpoint.Desktop, + Breakpoint.DesktopL, + Breakpoint.DesktopXL, + ]); + + template = ` + @if (isDesktop()) { + + } @else { + + } + `; +} +``` + +--- + +## Common Commands + +### Development +```bash +npm start # Start with SSL +npm test # Test all libraries +npm run build # Dev build +npm run build-prod # Production build +``` + +### Testing +```bash +npx nx test oms-data-access --skip-nx-cache +npx nx affected:test --skip-nx-cache +npm run ci # CI with coverage +``` + +### Code Quality +```bash +npm run lint # ESLint +npm run prettier # Format code +npm run docs:generate # Update library ref +``` + +### API & Swagger +```bash +npm run generate:swagger # Regenerate all APIs +npm run fix:files:swagger # Unicode cleanup +``` + +### Dependency Analysis +```bash +npx nx graph # Visual dependency graph +npx nx show project oms-data-access --web false +npx nx affected:lint --skip-nx-cache +``` + +--- + +## File Organization by Domain + +### OMS Domain Structure +``` +libs/oms/ +├── data-access/ +│ └── src/ +│ ├── index.ts +│ ├── stores/ +│ │ ├── receipt.store.ts +│ │ └── return.store.ts +│ └── services/ +│ ├── oms-api.service.ts +│ └── print.service.ts +├── feature/ +│ ├── return-search/ +│ ├── return-details/ +│ ├── return-process/ +│ ├── return-summary/ +│ └── return-review/ +├── shared/ +│ ├── product-info/ +│ └── task-list/ +└── utils/ + └── translation/ +``` + +### UI Component Structure +``` +libs/ui/buttons/ +├── src/ +│ ├── index.ts +│ ├── primary-button.component.ts +│ ├── secondary-button.component.ts +│ ├── ... +│ └── buttons.module.ts +├── README.md +├── project.json +└── ... +``` + +--- + +## TypeScript Path Aliases + +```json +{ + "paths": { + // Domain data-access + "@isa/oms/data-access": ["libs/oms/data-access/src/index.ts"], + "@isa/remission/data-access": ["libs/remission/data-access/src/index.ts"], + + // UI components + "@isa/ui/buttons": ["libs/ui/buttons/src/index.ts"], + "@isa/ui/dialog": ["libs/ui/dialog/src/index.ts"], + + // Core infrastructure + "@isa/core/logging": ["libs/core/logging/src/index.ts"], + "@isa/core/storage": ["libs/core/storage/src/index.ts"], + + // Generated APIs + "@generated/swagger/oms-api": ["generated/swagger/oms-api/src/index.ts"] + } +} +``` + +--- + +## Styling & Design System + +### Tailwind Utilities (ISA-Specific) + +```html + +
Primary text
+ + + +

Large heading

+

Body text

+ + + +
Mobile only
+ + + +
...
+``` + +### Custom Tailwind Plugins +1. button - Button styling +2. typography - Text utilities +3. menu - Menu styling +4. label - Label & tag styling +5. input - Input styling +6. section - Section containers +7. select-bullet - Select styling + +--- + +## Testing Approach + +### New Libraries (Vitest + Angular Testing Utils) +```typescript +import { TestBed, ComponentFixture } from '@angular/core/testing'; +import { OmsReturnSearchComponent } from './oms-return-search.component'; + +describe('OmsReturnSearchComponent', () => { + let component: OmsReturnSearchComponent; + let fixture: ComponentFixture; + + beforeEach(async () => { + await TestBed.configureTestingModule({ + imports: [OmsReturnSearchComponent], + }).compileComponents(); + + fixture = TestBed.createComponent(OmsReturnSearchComponent); + component = fixture.componentInstance; + fixture.detectChanges(); + }); + + it('should create', () => { + expect(component).toBeTruthy(); + }); +}); +``` + +### E2E Attributes +All templates must include data attributes: +```html + +``` + +--- + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| **Build cache stale** | `npx nx reset` or `--skip-nx-cache` | +| **Test failures** | Always use `--skip-nx-cache` | +| **Import not found** | Check `tsconfig.base.json` path alias | +| **Circular dependency** | Run `npx nx lint` to identify | +| **SSL certificate error** | Accept localhost certificate in browser | +| **State not persisting** | Check `withStorage()` in store | +| **API 401 Unauthorized** | Verify OAuth2 token in auth service | + +--- + +## Quick Links + +- **Library Reference:** `/docs/library-reference.md` +- **Architecture Analysis:** `/docs/architecture-analysis.md` +- **Dependency Hierarchy:** `/docs/dependency-hierarchy.md` +- **Testing Guidelines:** `/docs/guidelines/testing.md` +- **Nx Documentation:** https://nx.dev/ +- **Angular Documentation:** https://angular.io/ +- **NgRx Signals:** https://ngrx.io/guide/signals + +--- + +## Getting Help + +1. Check library README: `libs/[domain]/[layer]/[feature]/README.md` +2. Review existing examples in similar domains +3. Check `npx nx show project [project-name]` +4. Read CLAUDE.md for project-specific conventions +5. Review git history: `git log --oneline libs/[domain]` + +--- + +## Performance Budgets + +- **Main bundle:** 2MB warning, 5MB error (gzipped) +- **Initial load:** < 2s on 4G +- **Core (after auth):** < 5s + +**Bundle Analysis:** +```bash +npx nx build isa-app --configuration=production --stats-json +webpack-bundle-analyzer dist/isa-app/browser/stats.json +``` + +--- + +## Monorepo Statistics + +| Metric | Count | +|--------|-------| +| Total Libraries | 63 | +| Feature Components | 20 | +| UI Components | 17 | +| Data Access | 6 | +| Core Infrastructure | 5 | +| Shared Components | 7 | +| Utilities | 3 | +| Generated APIs | 10 | +| Lines of Code | ~500K+ | +| TypeScript Files | ~1,500 | +| Test Files | ~400 | +| Generated Test Coverage | Vitest: 34%, Jest: 65% | + diff --git a/docs/dependency-hierarchy.md b/docs/dependency-hierarchy.md new file mode 100644 index 000000000..dfebb9746 --- /dev/null +++ b/docs/dependency-hierarchy.md @@ -0,0 +1,458 @@ +# ISA-Frontend: Dependency Hierarchy Diagram + +## 1. Layer-Based Dependency Model + +``` +Level 4: Feature Components (Entry Points) +├── oms-feature-return-search +├── oms-feature-return-details +├── oms-feature-return-process +├── oms-feature-return-summary +├── oms-feature-return-review +├── remission-feature-remission-list +├── remission-feature-remission-return-receipt-list +├── remission-feature-remission-return-receipt-details +├── checkout-feature-reward-catalog +├── checkout-feature-reward-shopping-cart +└── checkout-feature-reward-order-confirmation + +Level 3: Shared & UI Components +├── OMS Shared +│ ├── oms-shared-product-info +│ └── oms-shared-task-list +├── Remission Shared +│ ├── remission-shared-product +│ ├── remission-shared-remission-start-dialog +│ ├── remission-shared-return-receipt-actions +│ └── remission-shared-search-item-to-remit-dialog +├── Checkout Shared +│ ├── checkout-shared-product-info +│ └── checkout-shared-reward-selection-dialog +└── UI Component Library (17) + ├── ui-buttons + ├── ui-input-controls + ├── ui-dialog + ├── ui-datepicker + ├── ui-layout + ├── ui-menu + ├── ui-toolbar + ├── ui-search-bar + ├── ui-expandable + ├── ui-empty-state + ├── ui-skeleton-loader + ├── ui-carousel + ├── ui-item-rows + ├── ui-progress-bar + ├── ui-tooltip + ├── ui-label + └── ui-bullet-list + +Level 2: Data Access Layer +├── oms-data-access +├── remission-data-access +├── checkout-data-access +├── catalogue-data-access +├── availability-data-access +└── crm-data-access + +Level 1: Infrastructure & Core +├── Core Libraries (5) +│ ├── core-config +│ ├── core-logging +│ ├── core-navigation +│ ├── core-storage +│ └── core-tabs +├── Common Utilities (3) +│ ├── common-data-access +│ ├── common-decorators +│ └── common-print +├── Shared Components (7) +│ ├── shared-address +│ ├── shared-filter +│ ├── shared-product-image +│ ├── shared-product-format +│ ├── shared-product-router-link +│ ├── shared-quantity-control +│ └── shared-scanner +├── Generated APIs (10) +│ ├── @generated/swagger/oms-api +│ ├── @generated/swagger/checkout-api +│ ├── @generated/swagger/crm-api +│ ├── @generated/swagger/cat-search-api +│ ├── @generated/swagger/availability-api +│ ├── @generated/swagger/isa-api +│ ├── @generated/swagger/eis-api +│ ├── @generated/swagger/inventory-api +│ ├── @generated/swagger/print-api +│ └── @generated/swagger/wws-api +└── Utilities (3) + ├── utils-ean-validation + ├── utils-scroll-position + └── utils-z-safe-parse +``` + +--- + +## 2. OMS Domain Dependency Tree + +``` +oms-feature-return-search +├── oms-data-access +│ ├── @generated/swagger/oms-api +│ ├── @generated/swagger/print-api +│ ├── @isa/core/logging +│ └── @isa/common/data-access +├── oms-shared-product-info +│ ├── shared-product-image +│ ├── shared-product-format +│ ├── ui-item-rows +│ └── ui-label +└── ui-* (search-bar, buttons, empty-state, etc.) + +oms-feature-return-details +├── oms-data-access (store) +├── oms-shared-product-info +├── ui-input-controls (quantity selector) +├── ui-buttons +└── shared-quantity-control + +oms-feature-return-process +├── oms-data-access (update store) +├── ui-input-controls (forms) +├── ui-buttons +└── common-data-access (validation) + +oms-feature-return-summary +├── oms-data-access (confirmation) +├── oms-shared-product-info +├── oms-shared-task-list +├── common-print (printing) +└── ui-buttons + +oms-feature-return-review +├── oms-data-access (state) +├── oms-shared-product-info +├── common-print (reprint) +└── ui-empty-state +``` + +--- + +## 3. Remission Domain Dependency Tree + +``` +remission-feature-remission-list +├── remission-data-access +│ ├── @generated/swagger/remission-api +│ ├── @isa/core/logging +│ └── @isa/common/data-access +├── remission-shared-remission-start-dialog +├── ui-dialog +├── ui-buttons +└── shared-filter + +remission-feature-remission-return-receipt-list +├── remission-data-access +├── remission-shared-search-item-to-remit-dialog +├── remission-shared-return-receipt-actions +├── ui-buttons +└── ui-empty-state + +remission-feature-remission-return-receipt-details +├── remission-data-access +├── remission-shared-product +│ ├── shared-product-image +│ ├── shared-product-format +│ └── ui-item-rows +├── remission-shared-return-receipt-actions +├── ui-expandable +└── ui-buttons +``` + +--- + +## 4. Checkout Domain Dependency Tree + +``` +checkout-feature-reward-shopping-cart +├── checkout-data-access +│ ├── @generated/swagger/checkout-api +│ ├── @generated/swagger/crm-api +│ ├── @isa/core/logging +│ └── @isa/common/data-access +├── checkout-shared-product-info +│ ├── shared-product-image +│ └── ui-item-rows +├── checkout-shared-reward-selection-dialog +├── shared-quantity-control +├── ui-buttons +└── ui-empty-state + +checkout-feature-reward-catalog +├── checkout-data-access +├── checkout-shared-product-info +├── shared-product-image +├── ui-buttons +├── ui-carousel +└── ui-skeleton-loader + +checkout-feature-reward-order-confirmation +├── checkout-data-access +├── checkout-shared-product-info +├── ui-buttons +└── shared-address +``` + +--- + +## 5. Complete Cross-Domain Dependency Matrix + +``` +Domain → Depends On +──────────────────────────────── +OMS Features → oms-data-access, oms-shared-*, ui-*, shared-* +OMS Data Access → @generated/swagger/*, core-*, common-* +Remission Features → remission-data-access, remission-shared-*, ui-*, shared-* +Remission D.A. → @generated/swagger/*, core-*, common-* +Checkout Features → checkout-data-access, checkout-shared-*, ui-*, shared-* +Checkout D.A. → @generated/swagger/*, core-*, common-* +Catalogue D.A. → @generated/swagger/*, core-*, common-* +Availability D.A. → @generated/swagger/*, core-*, common-* +CRM D.A. → @generated/swagger/crm-api, core-*, common-* +UI Components → core-config, common-*, no data-access deps +Shared Components → core-*, ui-*, no data-access deps +Core Libraries → No monorepo dependencies +Common Libraries → core-*, no domain deps +Generated APIs → External (backend) +Utilities → core-config, no domain deps +``` + +--- + +## 6. Import Path Conventions + +All imports follow strict path aliases: + +```typescript +// Domain-specific data-access +import { OrderStore, orderStore } from '@isa/oms/data-access'; +import { ReturnStore, returnStore } from '@isa/remission/data-access'; +import { CartStore, cartStore } from '@isa/checkout/data-access'; + +// Domain-specific shared components +import { OmsProductInfo } from '@isa/oms/shared/product-info'; +import { RemissionProduct } from '@isa/remission/shared/product'; +import { CheckoutProductInfo } from '@isa/checkout/shared/product-info'; + +// UI component library +import { UiButton, UiPrimaryButton } from '@isa/ui/buttons'; +import { UiDialog } from '@isa/ui/dialog'; +import { UiEmptyState } from '@isa/ui/empty-state'; + +// Shared components +import { SharedAddress } from '@isa/shared/address'; +import { SharedFilter } from '@isa/shared/filter'; +import { SharedProductImage } from '@isa/shared/product-image'; + +// Core infrastructure +import { Config } from '@isa/core/config'; +import { logger } from '@isa/core/logging'; +import { navigationState } from '@isa/core/navigation'; +import { storageProvider } from '@isa/core/storage'; +import { tabManager } from '@isa/core/tabs'; + +// Common utilities +import { tapResponse } from '@isa/common/data-access'; +import { Cached, Debounce } from '@isa/common/decorators'; +import { PrintService } from '@isa/common/print'; + +// General utilities +import { validateEan } from '@isa/utils/ean-validation'; +import { restoreScrollPosition } from '@isa/utils/scroll-position'; +import { safeParse } from '@isa/utils/z-safe-parse'; + +// Generated Swagger APIs +import { OmsApiClient } from '@generated/swagger/oms-api'; +import { CheckoutApiClient } from '@generated/swagger/checkout-api'; +import { CrmApiClient } from '@generated/swagger/crm-api'; +``` + +--- + +## 7. NO Circular Dependencies + +The architecture enforces strict acyclic dependencies: + +``` +Feature Layer (Level 4) + ↓ (one-way only) +Shared/UI Layer (Level 3) + ↓ (one-way only) +Data Access Layer (Level 2) + ↓ (one-way only) +Infrastructure Layer (Level 1) + ↓ (one-way only) +External APIs & Services (Backend) +``` + +**Verification Command:** +```bash +npx nx affected:lint --skip-nx-cache +``` + +--- + +## 8. Bundle Dependency Impact + +### Smallest Dependencies (Infrastructure) +- `core-config` (~2KB) +- `core-logging` (~5KB) +- `utils-ean-validation` (~3KB) + +### Medium Dependencies (Shared) +- `shared-product-image` (~8KB) +- `ui-buttons` (~12KB) +- `ui-input-controls` (~20KB) + +### Larger Dependencies (Domain) +- `oms-data-access` (~25KB including API client) +- `checkout-data-access` (~30KB including API client) +- `remission-data-access` (~20KB including API client) + +### Impact on Main Bundle +- All 63 libraries + isa-app = ~2MB (production gzipped) +- Tree-shaking removes unused code +- Lazy-loaded routes reduce initial load + +--- + +## 9. Development Workflow + +### Adding a New Feature + +``` +1. Create feature component + → Depends on shared components + +2. Create shared component (if needed) + → Depends on UI & core libraries + +3. Update data-access if needed + → Depends on generated APIs & common + +4. Import via path aliases + import { NewFeature } from '@isa/domain/feature/new-feature' + +5. Verify no circular deps + npx nx affected:lint +``` + +### Dependency Investigation + +```bash +# Show all dependencies of a library +npx nx show project oms-feature-return-search --web false + +# Visualize dependency graph +npx nx graph --filter=oms-data-access + +# Check for circular dependencies +npx nx lint + +# View detailed dependency tree +npx nx show project oms-data-access --web false +``` + +--- + +## 10. Performance Considerations + +### Lazy Loading +- Each feature module can be lazy-loaded via routing +- Reduces initial bundle size +- Loads on demand + +### Tree Shaking +- Unused exports automatically removed +- All libraries use ES6 modules +- Named exports encouraged + +### Code Splitting +- Generated APIs included only when imported +- UI components tree-shakeable +- Shared components bundled separately + +### Module Boundaries +``` +isa-app (main bundle) +├── core/ (always loaded) +├── routing (root) +└── route bundles (lazy) + ├── oms/ (on route navigation) + ├── remission/ (on route navigation) + └── checkout/ (on route navigation) +``` + +--- + +## 11. Breaking Changes Prevention + +Strict dependency enforcement prevents: +- ✅ Feature importing data-access from other features +- ✅ UI components importing domain logic +- ✅ Core libraries importing domain logic +- ✅ Circular dependencies +- ✅ Implicit dependencies + +Violations caught by: +1. ESLint nx plugin (import-rules) +2. TypeScript compiler (path alias validation) +3. Bundle analysis tools +4. Code review process + +--- + +## 12. Updating Dependencies + +### Safe Dependency Diagram Update +``` +1. Update generated API + → Automatically updates data-access + +2. Update core library + → Cascades to all dependent layers + +3. Update UI component + → Only affects features using it + +4. Update data-access + → Only affects features in domain +``` + +### Testing Strategy +- Update → Run affected tests → Deploy +- `npx nx affected:test --skip-nx-cache` + +--- + +## Quick Reference: Which Library to Import + +**I need a component for...** + +| Use Case | Import From | +|----------|------------| +| Button styling | `@isa/ui/buttons` | +| Form inputs | `@isa/ui/input-controls` | +| Modal dialog | `@isa/ui/dialog` | +| Data fetching | `@isa/[domain]/data-access` | +| Product display | `@isa/shared/product-*` | +| Address display | `@isa/shared/address` | +| Logging | `@isa/core/logging` | +| Configuration | `@isa/core/config` | +| State storage | `@isa/core/storage` | +| Tab navigation | `@isa/core/tabs` | +| Context preservation | `@isa/core/navigation` | +| Printer management | `@isa/common/print` | +| EAN validation | `@isa/utils/ean-validation` | +| API client | `@generated/swagger/[api-name]` | +