# ADR 0013: Environment and Infrastructure Topology

- Status: Accepted
- Date: 2026-03-11
- Owners: Platform Team, SRE Team, Security Team
- Related:
  - `docs/wallet-implementation-plan-apps-mode.md`
  - `docs/adr/0006-security-and-key-management-baseline.md`
  - `docs/adr/0007-observability-and-audit-traceability-standard.md`
  - `docs/adr/0010-release-strategy-and-migration-rollback.md`
  - `docs/non-functional-slo.md`
  - `docs/phase-tracker.md`

## Context
The wallet platform requires multiple environments and network zones to support secure development, validation, and production operations. Without an explicit topology standard, environment drift, weak isolation, and deployment risk increase.

This ADR defines the baseline environment model, zone boundaries, infrastructure patterns, and promotion alignment.

## Decision
Adopt a standardized multi-environment topology with strict zone separation and promotion parity.

Core decisions:
1. Use four primary environments: `dev`, `test/qa`, `staging`, `prod`.
2. Enforce network zoning aligned to architecture layers (edge, dmz, private core, data plane, observability plane).
3. Keep configuration parity across environments; vary only approved environment-specific settings.
4. Production is active-active across at least two zones/regions where feasible.
5. Infrastructure changes follow the same promotion and rollback governance as application changes.

## Environment Model
1. `dev`:
- Fast feedback environment for engineering teams.
- Lower data volume, synthetic data only.

2. `test/qa`:
- Integration and contract validation environment.
- Shared services for cross-domain testing.

3. `staging`:
- Production-like topology and configuration.
- Full release-candidate validation and operational rehearsals.

4. `prod`:
- Regulated runtime with strict access controls and monitoring.
- Controlled change windows and incident response requirements.

## Network and Zone Topology
Logical zones:
1. Edge zone:
- Global load balancer and API gateway ingress.

2. DMZ/security zone:
- Authentication edge services, rate limiting, token verification boundaries.

3. Private core zone:
- Wallet domain OTP apps and orchestration components.

4. Data zone:
- Financial databases, ledger stores, reconciliation data stores, event persistence.

5. Observability/security ops zone:
- Centralized telemetry, audit pipeline, SIEM integration.

Rules:
- No direct public ingress to private core or data zones.
- East-west traffic restricted by least privilege network policy.
- Admin access only through approved bastion/privileged workflows.

## Compute and Runtime Baseline
- Runtime supports horizontal scaling for stateless and worker services.
- Dedicated worker pools for high-priority queues and settlement workloads.
- Capacity reservations for financial critical paths.
- Resource quotas and limits enforced per app/domain.

## Data and Stateful Service Topology
- Financial SoR databases deployed with HA configuration.
- Read replicas allowed for non-critical read scaling with freshness policy.
- Backup strategy and restore testing aligned to DR requirements.
- Redis/cache/stateful components isolated by environment and security boundary.

## Configuration and Secret Management
- Environment config managed declaratively and version-controlled (excluding secrets).
- Secrets injected from centralized secret manager only.
- Configuration drift detection required between staging and production.

## Promotion and Change Control Alignment
- Promotion flow: `dev` -> `test/qa` -> `staging` -> `prod`.
- Promotion gates must include SLO and security checks.
- Infrastructure rollout supports canary/gradual expansion where possible.
- Emergency change process requires post-change review and evidence.

## Access and Operational Controls
- RBAC-based environment access with least privilege.
- Production write access restricted and audited.
- Break-glass access path with strict approval, expiry, and review.
- On-call routing and incident ownership defined per environment.

## Observability and Health Requirements
Per-environment minimums:
- service health checks and uptime dashboards
- latency/error/queue metrics
- alert routing and escalation policies
- audit event visibility and access logs

Environment-specific alerts:
- stricter thresholds in production
- noisy/non-critical alerts reduced in lower environments

## Cost and Capacity Governance
- Monthly capacity and spend review by environment.
- Autoscaling policies documented with max-guardrails.
- Cost anomaly detection and alerting enabled for production.

## Test and Verification Requirements
1. Environment parity checks between staging and production.
2. Network policy tests for zone isolation.
3. Access control and break-glass workflow tests.
4. Failover and autoscaling behavior tests in staging/pre-prod.
5. Configuration drift detection tests integrated in pipeline.

## Consequences
Positive:
- Stronger security posture via zoning and access boundaries.
- Better release confidence from environment parity.
- Improved operational resilience and incident clarity.

Trade-offs:
- Higher infrastructure and operational complexity.
- Additional overhead for drift and policy enforcement.

## Acceptance Criteria
1. Environment topology and ownership model documented and approved.
2. Zone-level network controls implemented and validated.
3. Staging-to-production parity checks operational.
4. Access and break-glass controls enforced with audit evidence.
5. Phase 8 readiness includes topology and environment control validation.