mirror of
https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend
synced 2025-12-28 22:42:11 +01:00
docs(architecture): add Architecture Decision Records (ADRs) documentation
Introduce a comprehensive guide for creating and maintaining ADRs within the ISA-Frontend project. This includes an overview, structure, naming conventions, and process guidelines to ensure consistent documentation of architectural decisions.
This commit is contained in:
Lorenz Hilpert
200
docs/architecture/README.md
Normal file
200
docs/architecture/README.md
Normal file
@@ -0,0 +1,200 @@
|
|||||||
|
# Architecture Decision Records (ADRs)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions made during the development of the ISA-Frontend project. They provide context for why certain decisions were made, helping current and future team members understand the reasoning behind architectural choices.
|
||||||
|
|
||||||
|
## What are ADRs?
|
||||||
|
|
||||||
|
An Architecture Decision Record is a document that captures a single architectural decision and its rationale. The goal of an ADR is to document the architectural decisions that are being made so that:
|
||||||
|
|
||||||
|
- **Future team members** can understand why certain decisions were made
|
||||||
|
- **Current team members** can refer back to the reasoning behind decisions
|
||||||
|
- **Architectural evolution** can be tracked over time
|
||||||
|
- **Knowledge transfer** is facilitated during team changes
|
||||||
|
|
||||||
|
## ADR Structure
|
||||||
|
|
||||||
|
Each ADR follows a consistent structure based on our [TEMPLATE.md](./TEMPLATE.md) and includes:
|
||||||
|
|
||||||
|
- **Problem Statement**: What architectural challenge needs to be addressed
|
||||||
|
- **Decision**: The architectural decision made
|
||||||
|
- **Rationale**: Why this decision was chosen
|
||||||
|
- **Consequences**: Both positive and negative outcomes of the decision
|
||||||
|
- **Alternatives**: Other options that were considered
|
||||||
|
- **Implementation**: Technical details and examples
|
||||||
|
- **Status**: Current state of the decision (Draft, Approved, Superseded, etc.)
|
||||||
|
|
||||||
|
## Naming Convention
|
||||||
|
|
||||||
|
ADRs should follow this naming pattern:
|
||||||
|
|
||||||
|
```
|
||||||
|
NNNN-short-descriptive-title.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Where:
|
||||||
|
- `NNNN` is a 4-digit sequential number (e.g., 0001, 0002, 0003...)
|
||||||
|
- `short-descriptive-title` uses kebab-case and briefly describes the decision
|
||||||
|
- `.md` indicates it's a Markdown file
|
||||||
|
|
||||||
|
### Examples:
|
||||||
|
- `0001-use-standalone-components.md`
|
||||||
|
- `0002-adopt-ngrx-signals.md`
|
||||||
|
- `0003-implement-micro-frontend-architecture.md`
|
||||||
|
- `0004-choose-vitest-over-jest.md`
|
||||||
|
|
||||||
|
## Process Guidelines
|
||||||
|
|
||||||
|
### 1. When to Create an ADR
|
||||||
|
|
||||||
|
Create an ADR when making decisions about:
|
||||||
|
|
||||||
|
- **Architecture patterns** (e.g., micro-frontends, monorepo structure)
|
||||||
|
- **Technology choices** (e.g., testing frameworks, state management)
|
||||||
|
- **Development practices** (e.g., code organization, build processes)
|
||||||
|
- **Technical standards** (e.g., coding conventions, performance requirements)
|
||||||
|
- **Infrastructure decisions** (e.g., deployment strategies, CI/CD processes)
|
||||||
|
|
||||||
|
### 2. ADR Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
Draft → Under Review → Approved → [Superseded/Deprecated]
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Draft**: Initial version, being written
|
||||||
|
- **Under Review**: Shared with team for feedback and discussion
|
||||||
|
- **Approved**: Team has agreed and decision is implemented
|
||||||
|
- **Superseded**: Replaced by a newer ADR
|
||||||
|
- **Deprecated**: No longer applicable but kept for historical reference
|
||||||
|
|
||||||
|
### 3. Creation Process
|
||||||
|
|
||||||
|
1. **Identify the Need**: Recognize an architectural decision needs documentation
|
||||||
|
2. **Create from Template**: Copy [TEMPLATE.md](./TEMPLATE.md) to create new ADR
|
||||||
|
3. **Fill in Content**: Complete all sections with relevant information
|
||||||
|
4. **Set Status to Draft**: Mark the document as "Draft" initially
|
||||||
|
5. **Share for Review**: Present to team for discussion and feedback
|
||||||
|
6. **Iterate**: Update based on team input
|
||||||
|
7. **Approve**: Once consensus is reached, mark as "Approved"
|
||||||
|
8. **Implement**: Begin implementation of the architectural decision
|
||||||
|
|
||||||
|
### 4. Review Process
|
||||||
|
|
||||||
|
- **Author Review**: Self-review for completeness and clarity
|
||||||
|
- **Peer Review**: Share with relevant team members for technical review
|
||||||
|
- **Architecture Review**: Present in architecture meetings if significant
|
||||||
|
- **Final Approval**: Get sign-off from technical leads/architects
|
||||||
|
|
||||||
|
## Angular/Nx Specific Considerations
|
||||||
|
|
||||||
|
When writing ADRs for this project, consider these Angular/Nx specific aspects:
|
||||||
|
|
||||||
|
### Architecture Decisions
|
||||||
|
- **Library organization** in the monorepo structure
|
||||||
|
- **Dependency management** between applications and libraries
|
||||||
|
- **Feature module vs. standalone component** approaches
|
||||||
|
- **State management patterns** (NgRx, Signals, Services)
|
||||||
|
- **Routing strategies** for large applications
|
||||||
|
|
||||||
|
### Technical Decisions
|
||||||
|
- **Build optimization** strategies using Nx
|
||||||
|
- **Testing approaches** for different types of libraries
|
||||||
|
- **Code sharing patterns** across applications
|
||||||
|
- **Performance optimization** techniques
|
||||||
|
- **Bundle splitting** and lazy loading strategies
|
||||||
|
|
||||||
|
### Development Workflow
|
||||||
|
- **Nx executor usage** for custom tasks
|
||||||
|
- **Generator patterns** for code scaffolding
|
||||||
|
- **Linting and formatting** configurations
|
||||||
|
- **CI/CD pipeline** optimizations using Nx affected commands
|
||||||
|
|
||||||
|
## Template Usage
|
||||||
|
|
||||||
|
### Getting Started
|
||||||
|
|
||||||
|
1. Copy the [TEMPLATE.md](./TEMPLATE.md) file
|
||||||
|
2. Rename it following the naming convention
|
||||||
|
3. Replace placeholder text with actual content
|
||||||
|
4. Focus on the "why" not just the "what"
|
||||||
|
5. Include concrete examples and code snippets
|
||||||
|
6. Consider both immediate and long-term consequences
|
||||||
|
|
||||||
|
### Key Template Sections
|
||||||
|
|
||||||
|
- **Decision**: State the architectural decision clearly and concisely
|
||||||
|
- **Context**: Provide background information and constraints
|
||||||
|
- **Consequences**: Be honest about both benefits and drawbacks
|
||||||
|
- **Implementation**: Include practical examples relevant to Angular/Nx
|
||||||
|
- **Alternatives**: Show you considered other options
|
||||||
|
|
||||||
|
## Examples of Good ADRs
|
||||||
|
|
||||||
|
Here are some example titles that would make good ADRs for this project:
|
||||||
|
|
||||||
|
- **State Management**: "0001-adopt-ngrx-signals-for-component-state.md"
|
||||||
|
- **Testing Strategy**: "0002-use-angular-testing-utilities-over-spectator.md"
|
||||||
|
- **Code Organization**: "0003-implement-domain-driven-library-structure.md"
|
||||||
|
- **Performance**: "0004-implement-lazy-loading-for-feature-modules.md"
|
||||||
|
- **Build Process**: "0005-use-nx-cloud-for-distributed-task-execution.md"
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Writing Effective ADRs
|
||||||
|
|
||||||
|
1. **Be Concise**: Keep it focused and to the point
|
||||||
|
2. **Be Specific**: Include concrete examples and implementation details
|
||||||
|
3. **Be Honest**: Document both pros and cons honestly
|
||||||
|
4. **Be Timely**: Write ADRs close to when decisions are made
|
||||||
|
5. **Be Collaborative**: Involve relevant team members in the process
|
||||||
|
|
||||||
|
### Maintenance
|
||||||
|
|
||||||
|
- **Review Regularly**: Check ADRs during architecture reviews
|
||||||
|
- **Update Status**: Keep status current as decisions evolve
|
||||||
|
- **Link Related ADRs**: Reference connected decisions
|
||||||
|
- **Archive Outdated**: Mark superseded ADRs appropriately
|
||||||
|
|
||||||
|
### Code Examples
|
||||||
|
|
||||||
|
When including code examples:
|
||||||
|
- Use actual project syntax and patterns
|
||||||
|
- Include both TypeScript and template examples where relevant
|
||||||
|
- Show before/after scenarios for changes
|
||||||
|
- Reference specific files in the codebase when possible
|
||||||
|
|
||||||
|
## Tools and Integration
|
||||||
|
|
||||||
|
### Recommended Tools
|
||||||
|
|
||||||
|
- **Markdown Editor**: Use any markdown-capable editor
|
||||||
|
- **Version Control**: All ADRs are tracked in Git
|
||||||
|
- **Review Process**: Use PR reviews for ADR approval
|
||||||
|
- **Documentation**: Link ADRs from relevant code comments
|
||||||
|
|
||||||
|
### Integration with Development
|
||||||
|
|
||||||
|
- Reference ADR numbers in commit messages when implementing decisions
|
||||||
|
- Include ADR links in PR descriptions for architectural changes
|
||||||
|
- Update ADRs when decisions need modification
|
||||||
|
- Use ADRs as reference during code reviews
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
### Questions or Issues?
|
||||||
|
|
||||||
|
- **Team Discussions**: Bring up in team meetings or Slack
|
||||||
|
- **Architecture Review**: Present in architecture meetings
|
||||||
|
- **Documentation**: Update this README if process improvements are needed
|
||||||
|
|
||||||
|
### Resources
|
||||||
|
|
||||||
|
- [Architecture Decision Records (ADRs) - Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
|
||||||
|
- [ADR GitHub Organization](https://adr.github.io/)
|
||||||
|
- [Nx Documentation](https://nx.dev/getting-started/intro)
|
||||||
|
- [Angular Architecture Guide](https://angular.dev/guide/architecture)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This ADR system helps maintain architectural consistency and knowledge sharing across the ISA-Frontend project. Keep it updated and use it regularly for the best results.*
|
||||||
138
docs/architecture/TEMPLATE.md
Normal file
138
docs/architecture/TEMPLATE.md
Normal file
@@ -0,0 +1,138 @@
|
|||||||
|
# ADR NNNN: <short-descriptive-title>
|
||||||
|
|
||||||
|
| Field | Value |
|
||||||
|
|-------|-------|
|
||||||
|
| Status | Draft / Under Review / Approved / Superseded by ADR NNNN / Deprecated |
|
||||||
|
| Date | YYYY-MM-DD |
|
||||||
|
| Owners | <author(s)> |
|
||||||
|
| Participants | <key reviewers / stakeholders> |
|
||||||
|
| Related ADRs | NNNN (title), NNNN (title) |
|
||||||
|
| Tags | architecture, <domain>, <category> |
|
||||||
|
|
||||||
|
---
|
||||||
|
## Summary (Decision in One Sentence)
|
||||||
|
Concise statement of the architectural decision. Avoid rationale here—just the what.
|
||||||
|
|
||||||
|
## Context & Problem Statement
|
||||||
|
Describe the background and the problem this decision addresses.
|
||||||
|
- Business drivers / user needs
|
||||||
|
- Technical constraints (performance, security, scalability, compliance, legacy, regulatory)
|
||||||
|
- Current pain points / gaps
|
||||||
|
- Measurable goals / success criteria (e.g. reduce build time by 30%)
|
||||||
|
|
||||||
|
### Scope
|
||||||
|
What is in scope and explicitly out of scope for this decision.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
State the decision clearly (active voice). Include high-level approach or pattern selection, not implementation detail.
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
Why this option was selected:
|
||||||
|
- Alignment with strategic/technical direction
|
||||||
|
- Trade-offs considered
|
||||||
|
- Data, benchmarks, experiments, spikes
|
||||||
|
- Impact on developer experience / velocity
|
||||||
|
- Long-term maintainability & extensibility
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
| Alternative | Summary | Pros | Cons | Reason Not Chosen |
|
||||||
|
|-------------|---------|------|------|-------------------|
|
||||||
|
| Option A | | | | |
|
||||||
|
| Option B | | | | |
|
||||||
|
| Option C | | | | |
|
||||||
|
|
||||||
|
Add deeper detail below if needed:
|
||||||
|
### Option A – <name>
|
||||||
|
### Option B – <name>
|
||||||
|
### Option C – <name>
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
### Positive
|
||||||
|
- …
|
||||||
|
### Negative / Risks / Debt Introduced
|
||||||
|
- …
|
||||||
|
### Neutral / Open Questions
|
||||||
|
- …
|
||||||
|
|
||||||
|
## Implementation Plan
|
||||||
|
High-level rollout strategy. Break into phases if applicable.
|
||||||
|
1. Phase 0 – Spike / Validation
|
||||||
|
2. Phase 1 – Foundation / Infrastructure
|
||||||
|
3. Phase 2 – Incremental Adoption / Migration
|
||||||
|
4. Phase 3 – Hardening / Optimization
|
||||||
|
5. Phase 4 – Decommission Legacy
|
||||||
|
|
||||||
|
### Tasks / Workstreams
|
||||||
|
- Infra / tooling changes
|
||||||
|
- Library additions (Nx generators, new libs under `libs/<domain>`)
|
||||||
|
- Refactors / migrations
|
||||||
|
- Testing strategy updates (Jest → Vitest, Signals adoption, etc.)
|
||||||
|
- Documentation & onboarding materials
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
List objective criteria to mark implementation complete.
|
||||||
|
|
||||||
|
### Rollback Plan
|
||||||
|
How to revert safely if outcomes are negative.
|
||||||
|
|
||||||
|
## Architectural Impact
|
||||||
|
### Nx / Monorepo Layout
|
||||||
|
Describe changes to library boundaries, tags, dependency graph, affected projects.
|
||||||
|
### Module / Library Design
|
||||||
|
New or modified public APIs (`src/index.ts` changes, path aliases additions to `tsconfig.base.json`).
|
||||||
|
### State Management
|
||||||
|
Implications for Signals, NgRx, resource factories, persistence patterns (`withStorage`).
|
||||||
|
### Runtime & Performance
|
||||||
|
Bundle size, lazy loading, code splitting, caching, SSR/hydration considerations.
|
||||||
|
### Security & Compliance
|
||||||
|
AuthZ/AuthN, token handling, data residency, PII, secure storage.
|
||||||
|
### Observability & Logging
|
||||||
|
Logging contexts (`@isa/core/logging`), metrics, tracing hooks.
|
||||||
|
### DX / Tooling
|
||||||
|
Generators, lint rules, schematic updates, local dev flow.
|
||||||
|
|
||||||
|
## Detailed Design Elements
|
||||||
|
(Optional deeper technical articulation.)
|
||||||
|
- Sequence diagrams / component diagrams
|
||||||
|
- Data flow / async flow
|
||||||
|
- Error handling strategy
|
||||||
|
- Concurrency / cancellation (e.g. `rxMethod` + `switchMap` usage)
|
||||||
|
- Abstractions & extension points
|
||||||
|
|
||||||
|
## Code Examples
|
||||||
|
### Before
|
||||||
|
```ts
|
||||||
|
// Previous approach (simplified)
|
||||||
|
```
|
||||||
|
### After
|
||||||
|
```ts
|
||||||
|
// New approach (simplified)
|
||||||
|
```
|
||||||
|
### Migration Snippet
|
||||||
|
```ts
|
||||||
|
// Example incremental migration pattern
|
||||||
|
```
|
||||||
|
|
||||||
|
## Open Questions / Follow-Ups
|
||||||
|
- Unresolved design clarifications
|
||||||
|
- Dependent ADRs required
|
||||||
|
- External approvals needed
|
||||||
|
|
||||||
|
## Decision Review & Revalidation
|
||||||
|
When and how this ADR will be re-evaluated (date, trigger conditions, metrics thresholds).
|
||||||
|
|
||||||
|
## Status Log
|
||||||
|
| Date | Change | Author |
|
||||||
|
|------|--------|--------|
|
||||||
|
| YYYY-MM-DD | Created (Draft) | |
|
||||||
|
| YYYY-MM-DD | Approved | |
|
||||||
|
| YYYY-MM-DD | Superseded by ADR NNNN | |
|
||||||
|
|
||||||
|
## References
|
||||||
|
- Links to spike notes, benchmark results
|
||||||
|
- External articles, standards, RFCs
|
||||||
|
- Related code PRs / commits
|
||||||
|
|
||||||
|
---
|
||||||
|
> Document updates MUST reference this ADR number in commit messages: `ADR-NNNN:` prefix.
|
||||||
|
> Keep this document updated through all lifecycle stages.
|
||||||
506
docs/architecture/adr/0001-implement-data-access-api-requests.md
Normal file
506
docs/architecture/adr/0001-implement-data-access-api-requests.md
Normal file
@@ -0,0 +1,506 @@
|
|||||||
|
# ADR 0001: Implement `data-access` API Requests
|
||||||
|
|
||||||
|
| Field | Value |
|
||||||
|
|-------|-------|
|
||||||
|
| Status | Draft |
|
||||||
|
| Date | 29.09.2025 |
|
||||||
|
| Owners | Lorenz, Nino |
|
||||||
|
| Participants | N/A |
|
||||||
|
| Related ADRs | N/A |
|
||||||
|
| Tags | architecture, data-access, library, swagger |
|
||||||
|
|
||||||
|
---
|
||||||
|
## Summary (Decision in One Sentence)
|
||||||
|
Standardize data-access library implementation patterns for API requests using Zod schemas for validation, domain-specific models extending generated DTOs, and service layers that integrate with generated Swagger clients.
|
||||||
|
|
||||||
|
## Context & Problem Statement
|
||||||
|
The ISA Frontend application requires consistent and maintainable patterns for implementing API requests across multiple domain libraries. Current data-access libraries show varying implementation approaches that need standardization.
|
||||||
|
|
||||||
|
**Business drivers / user needs:**
|
||||||
|
- Consistent error handling across all API interactions
|
||||||
|
- Type-safe request/response handling to prevent runtime errors
|
||||||
|
- Maintainable code structure for easy onboarding and development
|
||||||
|
- Reliable validation of API inputs and outputs
|
||||||
|
|
||||||
|
**Technical constraints:**
|
||||||
|
- Must integrate with generated Swagger clients (`@generated/swagger/*`)
|
||||||
|
- Need to support abort signals for request cancellation
|
||||||
|
- Require caching and performance optimization capabilities
|
||||||
|
- Must align with existing logging infrastructure (`@isa/core/logging`)
|
||||||
|
- Support for domain-specific model extensions beyond generated DTOs
|
||||||
|
|
||||||
|
**Current pain points:**
|
||||||
|
- Inconsistent validation patterns across different data-access libraries
|
||||||
|
- Mixed approaches to error handling and response processing
|
||||||
|
- Duplication of common patterns (abort signal handling, response parsing)
|
||||||
|
- Lack of standardized model extension patterns
|
||||||
|
|
||||||
|
**Measurable goals:**
|
||||||
|
- Standardize API request patterns across all 4+ data-access libraries
|
||||||
|
- Reduce boilerplate code by 40% through shared utilities
|
||||||
|
- Improve type safety with comprehensive Zod schema coverage
|
||||||
|
|
||||||
|
### Scope
|
||||||
|
**In scope:**
|
||||||
|
- Schema validation patterns using Zod
|
||||||
|
- Model definition standards extending generated DTOs
|
||||||
|
- Service implementation patterns with generated Swagger clients
|
||||||
|
- Error handling and response processing standardization
|
||||||
|
- Integration with common utilities and logging
|
||||||
|
|
||||||
|
**Out of scope:**
|
||||||
|
- Modification of generated Swagger client code
|
||||||
|
- Changes to backend API contracts
|
||||||
|
- Authentication/authorization mechanisms
|
||||||
|
- Caching implementation details (handled by decorators)
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
Implement a three-layer architecture pattern for data-access libraries:
|
||||||
|
|
||||||
|
1. **Schema Layer**: Use Zod schemas for input validation and type inference, following the naming convention `<Operation>Schema` with corresponding `<Operation>` and `<Operation>Input` types
|
||||||
|
2. **Model Layer**: Define domain-specific interfaces that extend generated DTOs, using `EntityContainer<T>` pattern for lazy-loaded relationships
|
||||||
|
3. **Service Layer**: Create injectable services that integrate generated Swagger clients, implement standardized error handling, and support request cancellation via AbortSignal
|
||||||
|
|
||||||
|
All data-access libraries will follow the standard export structure: `models`, `schemas`, `services`, and optionally `stores` and `helpers`.
|
||||||
|
|
||||||
|
## Rationale
|
||||||
|
**Alignment with strategic/technical direction:**
|
||||||
|
- Leverages existing Zod integration for consistent validation across the application
|
||||||
|
- Builds upon established generated Swagger client infrastructure
|
||||||
|
- Aligns with Angular dependency injection patterns and service architecture
|
||||||
|
- Supports the project's type-safety goals with TypeScript
|
||||||
|
|
||||||
|
**Trade-offs considered:**
|
||||||
|
- **Schema validation overhead**: Zod validation adds minimal runtime cost but provides significant development-time safety
|
||||||
|
- **Model extension complexity**: Interface extension pattern adds a layer but enables domain-specific enhancements
|
||||||
|
- **Service layer abstraction**: Additional abstraction over generated clients but enables consistent error handling and logging
|
||||||
|
|
||||||
|
**Evidence from current implementation:**
|
||||||
|
- Analysis of 4 data-access libraries shows successful patterns in `catalogue`, `remission`, `crm`, and `oms`
|
||||||
|
- `RemissionReturnReceiptService` demonstrates effective integration with logging and error handling
|
||||||
|
- `EntityContainer<T>` pattern proven effective for lazy-loaded relationships in remission domain
|
||||||
|
|
||||||
|
**Developer experience impact:**
|
||||||
|
- Consistent patterns reduce cognitive load when switching between domains
|
||||||
|
- Type inference from Zod schemas eliminates manual type definitions
|
||||||
|
- Standardized error handling reduces debugging time
|
||||||
|
- Auto-completion and type safety improve development velocity
|
||||||
|
|
||||||
|
**Long-term maintainability:**
|
||||||
|
- Clear separation of concerns between validation, models, and API integration
|
||||||
|
- Generated client changes don't break domain-specific model extensions
|
||||||
|
- Consistent logging and error handling simplifies troubleshooting
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
| Alternative | Summary | Pros | Cons | Reason Not Chosen |
|
||||||
|
|-------------|---------|------|------|-------------------|
|
||||||
|
| Option A | | | | |
|
||||||
|
| Option B | | | | |
|
||||||
|
| Option C | | | | |
|
||||||
|
|
||||||
|
Add deeper detail below if needed:
|
||||||
|
### Option A – <name>
|
||||||
|
### Option B – <name>
|
||||||
|
### Option C – <name>
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
### Positive
|
||||||
|
- …
|
||||||
|
### Negative / Risks / Debt Introduced
|
||||||
|
- …
|
||||||
|
### Neutral / Open Questions
|
||||||
|
- …
|
||||||
|
|
||||||
|
## Implementation Plan
|
||||||
|
|
||||||
|
### Phase 0 – Analysis & Standards (Completed)
|
||||||
|
- ✅ Analyzed existing data-access libraries (`catalogue`, `remission`, `crm`, `oms`)
|
||||||
|
- ✅ Identified common patterns and best practices
|
||||||
|
- ✅ Documented standard library structure
|
||||||
|
|
||||||
|
### Phase 1 – Common Utilities Enhancement
|
||||||
|
- Enhance `@isa/common/data-access` with additional utilities
|
||||||
|
- Add standardized error types and response handling
|
||||||
|
- Create reusable operators and decorators
|
||||||
|
- Add helper functions for common API patterns
|
||||||
|
|
||||||
|
### Phase 2 – Template & Generator Creation
|
||||||
|
- Create Nx generator for new data-access libraries
|
||||||
|
- Develop template files for schemas, models, and services
|
||||||
|
- Add code snippets and documentation templates
|
||||||
|
- Create migration guide for existing libraries
|
||||||
|
|
||||||
|
### Phase 3 – Existing Library Standardization
|
||||||
|
- Update `catalogue/data-access` to follow complete pattern
|
||||||
|
- Migrate `crm/data-access` to standard structure
|
||||||
|
- Ensure `remission/data-access` follows all conventions
|
||||||
|
- Standardize `oms/data-access` implementation
|
||||||
|
|
||||||
|
### Phase 4 – New Library Implementation
|
||||||
|
- Apply patterns to new domain libraries as they're created
|
||||||
|
- Use Nx generator for consistent setup
|
||||||
|
- Enforce patterns through code review and linting
|
||||||
|
|
||||||
|
### Tasks / Workstreams
|
||||||
|
**Infrastructure:**
|
||||||
|
- Update `@isa/common/data-access` with enhanced utilities
|
||||||
|
- Add ESLint rules for data-access pattern enforcement
|
||||||
|
- Update `tsconfig.base.json` path mappings as needed
|
||||||
|
|
||||||
|
**Library Enhancements:**
|
||||||
|
- Create Nx generator: `nx g @isa/generators:data-access-lib <domain>`
|
||||||
|
- Add utility functions to `@isa/common/data-access`
|
||||||
|
- Enhanced error handling and logging patterns
|
||||||
|
|
||||||
|
**Migration Tasks:**
|
||||||
|
- Standardize schema validation across all libraries
|
||||||
|
- Ensure consistent model extension patterns
|
||||||
|
- Align service implementations with logging standards
|
||||||
|
- Update tests to match new patterns
|
||||||
|
|
||||||
|
**Documentation:**
|
||||||
|
- Create data-access implementation guide
|
||||||
|
- Update onboarding materials with patterns
|
||||||
|
- Add code examples to development wiki
|
||||||
|
- Document generator usage and options
|
||||||
|
|
||||||
|
### Acceptance Criteria
|
||||||
|
- [ ] All data-access libraries follow standardized structure
|
||||||
|
- [ ] All API requests use Zod schema validation
|
||||||
|
- [ ] All services implement consistent error handling
|
||||||
|
- [ ] All services support AbortSignal for cancellation
|
||||||
|
- [ ] All models extend generated DTOs appropriately
|
||||||
|
- [ ] Nx generator produces compliant library structure
|
||||||
|
- [ ] Code review checklist includes data-access patterns
|
||||||
|
- [ ] Performance benchmarks show no degradation
|
||||||
|
|
||||||
|
### Rollback Plan
|
||||||
|
- Individual library changes can be reverted via Git
|
||||||
|
- Generated libraries can be recreated with previous patterns
|
||||||
|
- No breaking changes to existing public APIs
|
||||||
|
- Gradual migration allows for partial rollback by domain
|
||||||
|
|
||||||
|
## Architectural Impact
|
||||||
|
### Nx / Monorepo Layout
|
||||||
|
- Data-access libraries follow domain-based organization: `libs/<domain>/data-access/`
|
||||||
|
- Each library exports standard modules: `models`, `schemas`, `services`
|
||||||
|
- Dependencies on `@isa/common/data-access` for shared utilities
|
||||||
|
- Integration with generated Swagger clients via `@generated/swagger/<api-name>`
|
||||||
|
|
||||||
|
### Module / Library Design
|
||||||
|
**Standard public API structure (`src/index.ts`):**
|
||||||
|
```typescript
|
||||||
|
export * from './lib/models';
|
||||||
|
export * from './lib/schemas';
|
||||||
|
export * from './lib/services';
|
||||||
|
// Optional: stores, helpers
|
||||||
|
```
|
||||||
|
|
||||||
|
**Path aliases in `tsconfig.base.json`:**
|
||||||
|
- `@isa/<domain>/data-access` for each domain library
|
||||||
|
- `@generated/swagger/<api-name>` for generated clients
|
||||||
|
- `@isa/common/data-access` for shared utilities
|
||||||
|
|
||||||
|
### State Management
|
||||||
|
- Services integrate with NgRx signal stores in feature libraries
|
||||||
|
- `EntityContainer<T>` pattern supports lazy loading in state management
|
||||||
|
- Resource factory pattern used for async state management (see remission examples)
|
||||||
|
- Caching implemented via decorators (`@Cache`, `@InFlight`)
|
||||||
|
|
||||||
|
### Runtime & Performance
|
||||||
|
- Zod schema validation adds minimal runtime overhead
|
||||||
|
- Generated clients are tree-shakeable
|
||||||
|
- AbortSignal support enables request cancellation
|
||||||
|
- Caching decorators reduce redundant API calls
|
||||||
|
- `firstValueFrom` pattern avoids memory leaks from subscriptions
|
||||||
|
|
||||||
|
### Security & Compliance
|
||||||
|
- All API calls go through generated clients with consistent auth handling
|
||||||
|
- Input validation via Zod schemas prevents injection attacks
|
||||||
|
- AbortSignal support enables proper request cleanup
|
||||||
|
- Logging excludes sensitive data through structured context
|
||||||
|
|
||||||
|
### Observability & Logging
|
||||||
|
- Consistent logging via `@isa/core/logging` with service-level context
|
||||||
|
- Structured logging with operation context and request metadata
|
||||||
|
- Error logging includes request details without sensitive data
|
||||||
|
- Debug logging for development troubleshooting
|
||||||
|
|
||||||
|
### DX / Tooling
|
||||||
|
- Consistent patterns reduce learning curve across domains
|
||||||
|
- Type inference from Zod schemas eliminates manual type definitions
|
||||||
|
- Auto-completion from TypeScript interfaces
|
||||||
|
- Standard error handling patterns
|
||||||
|
|
||||||
|
## Detailed Design Elements
|
||||||
|
|
||||||
|
### Schema Validation Pattern
|
||||||
|
**Structure:**
|
||||||
|
```typescript
|
||||||
|
// Input validation schema
|
||||||
|
export const SearchByTermSchema = z.object({
|
||||||
|
searchTerm: z.string().min(1, 'Search term must not be empty'),
|
||||||
|
skip: z.number().int().min(0).default(0),
|
||||||
|
take: z.number().int().min(1).max(100).default(20),
|
||||||
|
});
|
||||||
|
|
||||||
|
// Type inference
|
||||||
|
export type SearchByTerm = z.infer<typeof SearchByTermSchema>;
|
||||||
|
export type SearchByTermInput = z.input<typeof SearchByTermSchema>;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Model Extension Pattern
|
||||||
|
**Generated DTO Extension:**
|
||||||
|
```typescript
|
||||||
|
import { ProductDTO } from '@generated/swagger/cat-search-api';
|
||||||
|
|
||||||
|
export interface Product extends ProductDTO {
|
||||||
|
name: string;
|
||||||
|
contributors: string;
|
||||||
|
catalogProductNumber: string;
|
||||||
|
// Domain-specific enhancements
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Entity Container Pattern:**
|
||||||
|
```typescript
|
||||||
|
export interface Return extends ReturnDTO {
|
||||||
|
id: number;
|
||||||
|
receipts: EntityContainer<Receipt>[]; // Lazy-loaded relationships
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Implementation Pattern
|
||||||
|
**Standard service structure:**
|
||||||
|
```typescript
|
||||||
|
@Injectable({ providedIn: 'root' })
|
||||||
|
export class DomainService {
|
||||||
|
#apiService = inject(GeneratedApiService);
|
||||||
|
#logger = logger(() => ({ service: 'DomainService' }));
|
||||||
|
|
||||||
|
async fetchData(params: InputType, abortSignal?: AbortSignal): Promise<ResultType> {
|
||||||
|
const validated = ValidationSchema.parse(params);
|
||||||
|
|
||||||
|
let req$ = this.#apiService.operation(validated);
|
||||||
|
if (abortSignal) {
|
||||||
|
req$ = req$.pipe(takeUntilAborted(abortSignal));
|
||||||
|
}
|
||||||
|
|
||||||
|
const res = await firstValueFrom(req$);
|
||||||
|
|
||||||
|
if (res.error) {
|
||||||
|
this.#logger.error('Operation failed', new Error(res.message));
|
||||||
|
throw new ResponseArgsError(res);
|
||||||
|
}
|
||||||
|
|
||||||
|
return res.result as ResultType;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Handling Strategy
|
||||||
|
1. **Input Validation**: Zod schemas validate and transform inputs
|
||||||
|
2. **API Error Handling**: Check `res.error` from generated clients
|
||||||
|
3. **Structured Logging**: Log errors with context via `@isa/core/logging`
|
||||||
|
4. **Error Propagation**: Throw `ResponseArgsError` for consistent handling
|
||||||
|
|
||||||
|
### Concurrency & Cancellation
|
||||||
|
- **AbortSignal Support**: All async operations accept optional AbortSignal
|
||||||
|
- **RxJS Integration**: Use `takeUntilAborted` operator for cancellation
|
||||||
|
- **Promise Pattern**: `firstValueFrom` prevents subscription memory leaks
|
||||||
|
- **Caching**: `@InFlight` decorator prevents duplicate concurrent requests
|
||||||
|
|
||||||
|
### Extension Points
|
||||||
|
- **Custom Decorators**: `@Cache`, `@InFlight`, `@CacheTimeToLive`
|
||||||
|
- **Schema Transformations**: Zod `.transform()` for data normalization
|
||||||
|
- **Model Inheritance**: Interface extension for domain-specific properties
|
||||||
|
- **Service Composition**: Services can depend on other domain services
|
||||||
|
|
||||||
|
## Code Examples
|
||||||
|
|
||||||
|
### Complete Data-Access Library Structure
|
||||||
|
```typescript
|
||||||
|
// libs/domain/data-access/src/lib/schemas/fetch-items.schema.ts
|
||||||
|
import { z } from 'zod';
|
||||||
|
|
||||||
|
export const FetchItemsSchema = z.object({
|
||||||
|
categoryId: z.string().min(1),
|
||||||
|
skip: z.number().int().min(0).default(0),
|
||||||
|
take: z.number().int().min(1).max(100).default(20),
|
||||||
|
filters: z.record(z.any()).default({}),
|
||||||
|
});
|
||||||
|
|
||||||
|
export type FetchItems = z.infer<typeof FetchItemsSchema>;
|
||||||
|
export type FetchItemsInput = z.input<typeof FetchItemsSchema>;
|
||||||
|
|
||||||
|
// libs/domain/data-access/src/lib/models/item.ts
|
||||||
|
import { ItemDTO } from '@generated/swagger/domain-api';
|
||||||
|
import { EntityContainer } from '@isa/common/data-access';
|
||||||
|
import { Category } from './category';
|
||||||
|
|
||||||
|
export interface Item extends ItemDTO {
|
||||||
|
id: number;
|
||||||
|
displayName: string;
|
||||||
|
category: EntityContainer<Category>;
|
||||||
|
// Domain-specific enhancements
|
||||||
|
isAvailable: boolean;
|
||||||
|
formattedPrice: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// libs/domain/data-access/src/lib/services/item.service.ts
|
||||||
|
import { inject, Injectable } from '@angular/core';
|
||||||
|
import { ItemService as GeneratedItemService } from '@generated/swagger/domain-api';
|
||||||
|
import { firstValueFrom } from 'rxjs';
|
||||||
|
import { takeUntilAborted, ResponseArgsError } from '@isa/common/data-access';
|
||||||
|
import { logger } from '@isa/core/logging';
|
||||||
|
import { FetchItemsInput, FetchItemsSchema } from '../schemas';
|
||||||
|
import { Item } from '../models';
|
||||||
|
|
||||||
|
@Injectable({ providedIn: 'root' })
|
||||||
|
export class ItemService {
|
||||||
|
#itemService = inject(GeneratedItemService);
|
||||||
|
#logger = logger(() => ({ service: 'ItemService' }));
|
||||||
|
|
||||||
|
async fetchItems(
|
||||||
|
params: FetchItemsInput,
|
||||||
|
abortSignal?: AbortSignal
|
||||||
|
): Promise<Item[]> {
|
||||||
|
this.#logger.debug('Fetching items', () => ({ params }));
|
||||||
|
|
||||||
|
const { categoryId, skip, take, filters } = FetchItemsSchema.parse(params);
|
||||||
|
|
||||||
|
let req$ = this.#itemService.getItems({
|
||||||
|
categoryId,
|
||||||
|
queryToken: { skip, take, filter: filters }
|
||||||
|
});
|
||||||
|
|
||||||
|
if (abortSignal) {
|
||||||
|
req$ = req$.pipe(takeUntilAborted(abortSignal));
|
||||||
|
}
|
||||||
|
|
||||||
|
const res = await firstValueFrom(req$);
|
||||||
|
|
||||||
|
if (res.error) {
|
||||||
|
this.#logger.error('Failed to fetch items', new Error(res.message));
|
||||||
|
throw new ResponseArgsError(res);
|
||||||
|
}
|
||||||
|
|
||||||
|
this.#logger.info('Successfully fetched items', () => ({
|
||||||
|
count: res.result?.length || 0
|
||||||
|
}));
|
||||||
|
|
||||||
|
return res.result as Item[];
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// libs/domain/data-access/src/index.ts
|
||||||
|
export * from './lib/models';
|
||||||
|
export * from './lib/schemas';
|
||||||
|
export * from './lib/services';
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage in Feature Components
|
||||||
|
```typescript
|
||||||
|
// feature component using the data-access library
|
||||||
|
import { Component, inject, signal } from '@angular/core';
|
||||||
|
import { ItemService, Item, FetchItemsInput } from '@isa/domain/data-access';
|
||||||
|
|
||||||
|
@Component({
|
||||||
|
selector: 'app-item-list',
|
||||||
|
template: `
|
||||||
|
@if (loading()) {
|
||||||
|
<div>Loading...</div>
|
||||||
|
} @else {
|
||||||
|
@for (item of items(); track item.id) {
|
||||||
|
<div>{{ item.displayName }}</div>
|
||||||
|
}
|
||||||
|
}
|
||||||
|
`
|
||||||
|
})
|
||||||
|
export class ItemListComponent {
|
||||||
|
#itemService = inject(ItemService);
|
||||||
|
|
||||||
|
items = signal<Item[]>([]);
|
||||||
|
loading = signal(false);
|
||||||
|
|
||||||
|
async loadItems(categoryId: string) {
|
||||||
|
this.loading.set(true);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const params: FetchItemsInput = {
|
||||||
|
categoryId,
|
||||||
|
take: 50,
|
||||||
|
filters: { active: true }
|
||||||
|
};
|
||||||
|
|
||||||
|
const items = await this.#itemService.fetchItems(params);
|
||||||
|
this.items.set(items);
|
||||||
|
} catch (error) {
|
||||||
|
console.error('Failed to load items', error);
|
||||||
|
} finally {
|
||||||
|
this.loading.set(false);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Migration Pattern for Existing Services
|
||||||
|
```typescript
|
||||||
|
// Before: Direct HTTP client usage
|
||||||
|
@Injectable()
|
||||||
|
export class LegacyItemService {
|
||||||
|
constructor(private http: HttpClient) {}
|
||||||
|
|
||||||
|
getItems(categoryId: string): Observable<any> {
|
||||||
|
return this.http.get(`/api/items?category=${categoryId}`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// After: Standardized data-access pattern
|
||||||
|
@Injectable({ providedIn: 'root' })
|
||||||
|
export class ItemService {
|
||||||
|
#itemService = inject(GeneratedItemService);
|
||||||
|
#logger = logger(() => ({ service: 'ItemService' }));
|
||||||
|
|
||||||
|
async fetchItems(params: FetchItemsInput, abortSignal?: AbortSignal): Promise<Item[]> {
|
||||||
|
const validated = FetchItemsSchema.parse(params);
|
||||||
|
// ... standard implementation pattern
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Open Questions / Follow-Ups
|
||||||
|
- Unresolved design clarifications
|
||||||
|
- Dependent ADRs required
|
||||||
|
- External approvals needed
|
||||||
|
|
||||||
|
## Decision Review & Revalidation
|
||||||
|
When and how this ADR will be re-evaluated (date, trigger conditions, metrics thresholds).
|
||||||
|
|
||||||
|
## Status Log
|
||||||
|
| Date | Change | Author |
|
||||||
|
|------|--------|--------|
|
||||||
|
| 2025-09-29 | Created (Draft) | Lorenz, Nino |
|
||||||
|
| 2025-09-25 | Analysis completed, comprehensive patterns documented | AI Assistant |
|
||||||
|
|
||||||
|
## References
|
||||||
|
**Existing Implementation Examples:**
|
||||||
|
- `libs/catalogue/data-access` - Basic schema and service patterns
|
||||||
|
- `libs/remission/data-access` - Advanced patterns with EntityContainer and stores
|
||||||
|
- `libs/common/data-access` - Shared utilities and response types
|
||||||
|
- `generated/swagger/` - Generated API clients integration
|
||||||
|
|
||||||
|
**Key Dependencies:**
|
||||||
|
- [Zod](https://github.com/colinhacks/zod) - Schema validation library
|
||||||
|
- [ng-swagger-gen](https://github.com/cyclosproject/ng-swagger-gen) - OpenAPI client generation
|
||||||
|
- `@isa/core/logging` - Structured logging infrastructure
|
||||||
|
- `@isa/common/data-access` - Shared utilities and types
|
||||||
|
|
||||||
|
**Related Documentation:**
|
||||||
|
- ISA Frontend Copilot Instructions - Data-access patterns
|
||||||
|
- Tech Stack Documentation - Architecture overview
|
||||||
|
- Code Style Guidelines - TypeScript and Angular patterns
|
||||||
|
|
||||||
|
---
|
||||||
|
> Document updates MUST reference this ADR number in commit messages: `ADR-NNNN:` prefix.
|
||||||
|
> Keep this document updated through all lifecycle stages.
|
||||||
Reference in New Issue
Block a user