b885e9c34b
Document the architectural decision for classifying BFF services: - Facades: unified entry points for integration subsystems - Orchestrators: coordinate workflows across multiple systems - Aggregators: read-only data composition from multiple sources - Services: single-responsibility operations Includes dependency rules, naming conventions, and implementation examples. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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 | Platform Events over Webhooks | Accepted | Use Salesforce Platform Events instead of inbound webhooks for provisioning |
| 002 | Zod-First Validation | Accepted | Zod schemas as single source of truth for validation |
| 003 | Map Once, Use Everywhere | Accepted | Single transformation point in domain mappers |
| 004 | Domain Provider Isolation | Accepted | Provider-specific code isolated in domain/providers/ |
| 005 | Feature Module Pattern | Accepted | Portal organized by feature modules with consistent structure |
| 006 | Thin Controllers | Accepted | Controllers handle HTTP only, delegate to services |
ADR Template
When adding new ADRs, use this template:
# 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