69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
|
# Architecture Decision Records (ADRs)
|
||
|
|
|
||
|
|
This folder documents key architectural decisions made in the Customer Portal project. Each ADR explains **what** was decided, **why** it was decided, and **what alternatives** were considered.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Why ADRs?
|
||
|
|
|
||
|
|
ADRs help AI tools and new developers understand:
|
||
|
|
|
||
|
|
- The reasoning behind non-obvious design choices
|
||
|
|
- Why certain patterns are used consistently
|
||
|
|
- What alternatives were rejected and why
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Decision Index
|
||
|
|
|
||
|
|
| ADR | Title | Status | Summary |
|
||
|
|
| --------------------------------------------- | ----------------------------- | -------- | --------------------------------------------------------------------------- |
|
||
|
|
| [001](./001-platform-events-over-webhooks.md) | Platform Events over Webhooks | Accepted | Use Salesforce Platform Events instead of inbound webhooks for provisioning |
|
||
|
|
| [002](./002-zod-first-validation.md) | Zod-First Validation | Accepted | Zod schemas as single source of truth for validation |
|
||
|
|
| [003](./003-map-once-use-everywhere.md) | Map Once, Use Everywhere | Accepted | Single transformation point in domain mappers |
|
||
|
|
| [004](./004-domain-provider-isolation.md) | Domain Provider Isolation | Accepted | Provider-specific code isolated in domain/providers/ |
|
||
|
|
| [005](./005-feature-module-pattern.md) | Feature Module Pattern | Accepted | Portal organized by feature modules with consistent structure |
|
||
|
|
| [006](./006-thin-controllers.md) | Thin Controllers | Accepted | Controllers handle HTTP only, delegate to services |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## ADR Template
|
||
|
|
|
||
|
|
When adding new ADRs, use this template:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
# ADR-XXX: Title
|
||
|
|
|
||
|
|
**Date**: YYYY-MM-DD
|
||
|
|
**Status**: Proposed | Accepted | Deprecated | Superseded
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
What is the issue or problem we're trying to solve?
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
What is the change that we're proposing and/or doing?
|
||
|
|
|
||
|
|
## Rationale
|
||
|
|
|
||
|
|
Why is this the best approach? What alternatives were considered?
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
What are the positive and negative outcomes of this decision?
|
||
|
|
|
||
|
|
## Related
|
||
|
|
|
||
|
|
- Links to related docs, code, or other ADRs
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Related Documentation
|
||
|
|
|
||
|
|
- [System Overview](../architecture/system-overview.md)
|
||
|
|
- [Domain Structure](../development/domain/structure.md)
|
||
|
|
- [BFF Integration Patterns](../development/bff/integration-patterns.md)
|
||
|
|
- [Portal Architecture](../development/portal/architecture.md)
|