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