# ADR 0001: Apps-Mode Boundaries and Dependency Rules

- Status: Accepted
- Date: 2026-03-10
- Owners: Architecture Group
- Related:
	- `docs/wallet-implementation-plan-apps-mode.md`
	- `docs/adr/0015-ui-composition-and-extension-architecture.md`

## Context
The wallet platform must support enterprise-grade financial consistency, event-driven processing, and clear ownership boundaries across domains. The current repository starts as a single Phoenix app and needs to evolve to apps mode with separated OTP applications.

Without strict boundaries, domain leakage and shared-kernel bloat will increase coupling and reduce maintainability.

## Decision
Adopt umbrella-style apps mode with explicit domain ownership and one-way dependency flow.

Target application set:
- `wallet_web`
- `wallet_api_contracts`
- `wallet_auth`
- `wallet_accounts`
- `wallet_cards`
- `wallet_ledger`
- `wallet_transfers`
- `wallet_limits_fees`
- `wallet_risk`
- `wallet_journey`
- `wallet_settlement`
- `wallet_notifications`
- `wallet_integrations`
- `wallet_gl`
- `wallet_reporting`
- `wallet_disputes`
- `wallet_loans`
- `wallet_insurance`
- `wallet_merchant`
- `wallet_rewards`
- `wallet_wps`
- `wallet_events`
- `wallet_state`
- `wallet_observability`
- `wallet_compliance`
- `wallet_resilience`
- `wallet_production`
- `wallet_database`
- `wallet_shared_kernel`

## Dependency Rules
Allowed dependency direction:
1. `wallet_web` -> domain apps via public service interfaces only.
2. Domain apps -> `wallet_events`, `wallet_observability`, `wallet_shared_kernel`.
3. `wallet_integrations` depends on domain ports/behaviors, never direct domain DBs.
4. `wallet_state` is usable by orchestrators and command handlers for non-financial state.
5. `wallet_shared_kernel` must be minimal and dependency-free.

Forbidden:
1. Any app reading another app's database tables directly.
2. `wallet_web` implementing financial domain logic.
3. Circular app dependencies.
4. Storing financial truth in `wallet_state` (ETS/Mnesia/Redis).

## System of Record Ownership
- Wallet account lifecycle SoR: `wallet_accounts`
- Card lifecycle SoR: `wallet_cards`
- Financial posting SoR: `wallet_ledger`
- GL posting and reconciliation SoR: `wallet_gl`
- Transfer lifecycle SoR: `wallet_transfers`
- External provider state SoR: `wallet_integrations`
- WPS salary credit lifecycle SoR: `wallet_wps`
- Loan lifecycle SoR: `wallet_loans`
- Insurance product and policy lifecycle SoR: `wallet_insurance`
- Merchant onboarding and transaction lifecycle SoR: `wallet_merchant`
- Rewards and points lifecycle SoR: `wallet_rewards`
- Dispute and refund lifecycle SoR: `wallet_disputes`
- Reporting request and schedule lifecycle SoR: `wallet_reporting`
- Resilience and SLO incident state SoR: `wallet_resilience`
- Production readiness and release state SoR: `wallet_production`
- Durable persistence SoR for domain records: `wallet_database`
- Audit/event lineage SoR: `wallet_events`

## Eventing and Integration
- Use versioned domain events for cross-app notifications.
- Use outbox/inbox reliability for external effects.
- Keep command processing deterministic and idempotent.

## Consequences
Positive:
- Better fault isolation and team autonomy by domain.
- Easier compliance traceability and audit evidence generation.
- Safer scaling and clearer ownership.

Trade-offs:
- Increased initial setup effort.
- More explicit contracts and coordination overhead.

## Compliance and Security Notes
- AuthN/AuthZ and OTP flows are isolated in `wallet_auth`.
- PII and sensitive values must be encrypted or externalized where appropriate.
- Correlation IDs are mandatory across inter-app calls/events.

## Implementation Notes
- Enforce boundary checks in CI (compile checks, static dependency checks).
- Require new ADR for boundary exceptions.
- Review `wallet_shared_kernel` quarterly to prevent growth beyond utility primitives.