mirror of
https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend
synced 2025-12-28 22:42:11 +01:00
🚚 refactor(skills): reorganize skill structure
- 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 <noreply@anthropic.com>
This commit is contained in:
Lorenz Hilpert
@@ -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:
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[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
|
||||
352
.claude/skills/git-workflow/SKILL.md
Normal file
352
.claude/skills/git-workflow/SKILL.md
Normal file
@@ -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**: `<type>/{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**: `<type>(<scope>): <description>`
|
||||
|
||||
**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 <noreply@anthropic.com>
|
||||
|
||||
# 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 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
## 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 <noreply@anthropic.com>" # 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
|
||||
<type>(<scope>): <description>
|
||||
|
||||
# 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`
|
||||
287
docs/ARCHITECTURE.md
Normal file
287
docs/ARCHITECTURE.md
Normal file
@@ -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
|
||||
<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)
|
||||
|
||||
1120
docs/architecture-analysis.md
Normal file
1120
docs/architecture-analysis.md
Normal file
File diff suppressed because it is too large
Load Diff
587
docs/architecture-quick-reference.md
Normal file
587
docs/architecture-quick-reference.md
Normal file
@@ -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<Order>() }),
|
||||
|
||||
// 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<void>(
|
||||
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: `
|
||||
<div class="container">
|
||||
<ui-search-bar (search)="onSearch($event)" />
|
||||
|
||||
@if (store.receipts(); as receipts) {
|
||||
@if (receipts.length > 0) {
|
||||
<oms-product-info
|
||||
*ngFor="let receipt of receipts"
|
||||
[receipt]="receipt"
|
||||
/>
|
||||
} @else {
|
||||
<ui-empty-state title="Keine Belege" />
|
||||
}
|
||||
} @loading {
|
||||
<ui-skeleton-loader />
|
||||
}
|
||||
</div>
|
||||
`,
|
||||
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<string>();
|
||||
|
||||
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()) {
|
||||
<desktop-layout />
|
||||
} @else {
|
||||
<mobile-layout />
|
||||
}
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
<!-- Brand Colors -->
|
||||
<div class="text-isa-accent-primary">Primary text</div>
|
||||
<button class="bg-isa-accent-primary">Primary button</button>
|
||||
|
||||
<!-- Typography -->
|
||||
<h1 class="isa-text-heading-1-bold">Large heading</h1>
|
||||
<p class="isa-text-body-2-regular">Body text</p>
|
||||
|
||||
<!-- Custom Breakpoints -->
|
||||
<div class="hidden isa-desktop:block">Desktop only</div>
|
||||
<div class="block isa-desktop:hidden">Mobile only</div>
|
||||
|
||||
<!-- Custom Plugins -->
|
||||
<button class="isa-button-primary">ISA Button</button>
|
||||
<div class="isa-input-group">...</div>
|
||||
```
|
||||
|
||||
### 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<OmsReturnSearchComponent>;
|
||||
|
||||
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
|
||||
<button
|
||||
data-what="submit-return"
|
||||
data-which="primary-action"
|
||||
[attr.data-order-id]="orderId"
|
||||
>
|
||||
Submit Return
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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% |
|
||||
|
||||
458
docs/dependency-hierarchy.md
Normal file
458
docs/dependency-hierarchy.md
Normal file
@@ -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]` |
|
||||
|
||||
Reference in New Issue
Block a user