ADR-0004: Maximum Portability as Overriding Architectural Principle¶
Status: Accepted
Date: 2026-03-23
Foundation doc: 01-PROJECT-FOUNDATION.md
Context¶
The AgenticAI platform is initially hosted on AWS. However, the business requires the ability to migrate to any cloud provider or bare-metal infrastructure with minimal effort and no application code changes. This constraint arises from commercial flexibility requirements and risk mitigation against vendor lock-in.
Decision¶
Every technical decision is evaluated against one overriding constraint: the system must be able to move between cloud providers or run on bare metal with minimal code changes.
This is implemented through 5 portability requirements: 1. All application code lives in git. 2. All services run in Docker containers, deployable to any Docker-compatible environment. 3. All deployment configuration is codified and version-controlled. 4. Data is backed up automatically to 3 geographically separate locations. 5. No cloud-provider-specific service is a critical dependency in the application layer.
Alternatives Considered¶
| Option | Why Not |
|---|---|
| AWS-native architecture (Lambda, DynamoDB, SQS, Aurora) | Maximum AWS performance and integration, but creates deep vendor lock-in. Migration would require rewriting application code, not just reconfiguring infrastructure. |
| Multi-cloud abstraction (Terraform + cloud-agnostic services) | Adds complexity without benefit — the application doesn't need multi-cloud; it needs the ability to move if needed. |
| Portability as secondary concern | Would allow faster development by using managed services, but creates long-term risk and removes negotiating leverage with AWS. |
Consequences¶
Positive: - Complete migration path documented: provision VM, install Docker, pull images, restore data, update DNS. No code changes. - Technology choices (MySQL over Aurora, Redis over ElastiCache, Caddy over ALB) are all swappable via environment variables. - Laravel's abstraction layers (Storage facade, Queue driver, Mail driver) ensure provider-specific code is isolated to configuration. - Kamal deployment works on any SSH-accessible server.
Negative: - Cannot use AWS-native performance optimisations (Aurora auto-scaling, SQS with Lambda triggers, CloudFront Functions). - Some operational tasks (scaling, monitoring) require more manual configuration than managed equivalents. - Team must evaluate every new dependency and integration against the portability principle.
Excluded services: Lambda, Step Functions, DynamoDB, SQS, SNS, Cognito, Aurora Serverless, API Gateway, CloudFront Functions/Lambda@Edge, ECS/Fargate. See 01-PROJECT-FOUNDATION.md for the complete list.