# 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.