Infrastructure Architecture
Purpose
This document defines the infrastructure and deployment architecture for the Farmer1st platform.
Current State
High-Level Infrastructure Diagram
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FARMER1ST INFRASTRUCTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ CLIENTS │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ Farmer PWA │ │ Stakeholder │ │
│ │ (Mobile) │ │ Portals (Web) │ │
│ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │
│ └──────────┬──────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CLOUDFLARE │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │
│ │ │ Cloudflare │ │ JWT Token │ │ Cloudflare │ │ │
│ │ │ Pages (PWA) │ │ Validation │ │ Tunnel │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Static │ │ • Verify │ │ • Secure link │ │ │
│ │ │ hosting │ │ tokens │ │ to AWS │ │ │
│ │ │ • Global CDN │ │ • Before │ │ • No public │ │ │
│ │ │ • Edge │ │ backend │ │ endpoints │ │ │
│ │ └─────────────────┘ └─────────────────┘ └────────┬─────────┘ │ │
│ └─────────────────────────────────────────────────────────┼───────────────┘ │
│ │ │
│ │ (Private tunnel) │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ AWS │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ EKS FARGATE (→ EC2 later) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │
│ │ │ │ API │ │ SuperTokens │ │ Temporal │ │ │ │
│ │ │ │ Services │ │ (Auth) │ │ (Workflows) │ │ │ │
│ │ │ │ (Python) │ │ │ │ │ │ │ │
│ │ │ └──────┬──────┘ └─────────────┘ └─────────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ └──────────┼────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────┴──────────────────────────────────────────────────────┐ │ │
│ │ │ DATA & MESSAGING │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │
│ │ │ │ PostgreSQL │ │ Redis │ │ MSK (Kafka) │ │ │ │
│ │ │ │ (RDS) │ │ (Elasticache│ │ (Async messaging) │ │ │ │
│ │ │ │ │ │ or self) │ │ │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Decisions and Rationale
Edge & CDN Layer
| Decision |
Choice |
Rationale |
| PWA Hosting |
Cloudflare Pages |
Global CDN, edge deployment, excellent performance for static PWA assets |
| API Gateway/Auth |
Cloudflare (JWT validation) |
Edge-level security, reduces load on backend, low latency token validation |
| Backend Connectivity |
Cloudflare Tunnel |
No public endpoints exposed, secure private connectivity, simplified networking |
Compute Layer
| Decision |
Choice |
Rationale |
| Container Orchestration |
AWS EKS |
Industry standard Kubernetes, managed control plane |
| Initial Compute |
Fargate |
Serverless containers, no node management, pay-per-use, good for initial scale |
| Future Compute |
EC2 (planned) |
Cost optimization at scale, more control, reserved capacity pricing |
Data Layer
| Decision |
Choice |
Rationale |
| Primary Database |
PostgreSQL |
ACID compliance, relational data, excellent ecosystem, proven at scale |
| Cache |
Redis |
Industry standard, sub-millisecond latency, versatile (cache, sessions, pub/sub) |
| Message Queue |
MSK (Kafka) |
Durable messaging, event sourcing capability, high throughput, AWS managed |
Workflow & Processing
| Decision |
Choice |
Rationale |
| Workflow Orchestration |
Temporal |
Complex workflow support, durability, retries, long-running processes |
| Async Processing |
Kafka (MSK) |
Decoupled services, event-driven architecture, replay capability |
Authentication
| Decision |
Choice |
Rationale |
| Auth Provider |
SuperTokens (self-hosted) |
Full control, no vendor lock-in, customizable, cost-effective at scale |
Trade-offs Considered
Fargate vs EC2 (Initial Choice: Fargate)
| Fargate Pros |
Fargate Cons |
| No node management |
Higher per-unit cost |
| Auto-scaling built-in |
Less control over instance types |
| Pay only for running containers |
Cold start latency |
| Faster time to market |
Limited GPU support |
Plan: Start with Fargate for simplicity, migrate to EC2 when scale justifies cost optimization.
Cloudflare Tunnel vs VPN/Direct Connect
| Tunnel Pros |
Tunnel Cons |
| No public IPs needed |
Dependency on Cloudflare |
| Simple setup |
Additional hop in network path |
| Built-in DDoS protection |
Less control over routing |
| Zero Trust security model |
|
MSK vs Self-managed Kafka vs SQS
| MSK Pros |
MSK Cons |
| Managed Kafka |
Higher cost than SQS |
| Familiar Kafka APIs |
Complexity for simple use cases |
| Event replay capability |
Operational overhead still exists |
| High throughput |
|
Decision: MSK chosen for event replay capability and future event sourcing patterns.
SuperTokens vs Auth0 vs Cognito
| SuperTokens Pros |
SuperTokens Cons |
| Self-hosted, full control |
Operational responsibility |
| No per-user pricing |
Smaller community than Auth0 |
| Customizable flows |
Less out-of-box integrations |
| Open source core |
|
Decision: SuperTokens chosen for cost control at millions of users scale.
Request Flow
1. User opens PWA
│
2. Cloudflare Pages serves static assets (cached at edge)
│
3. PWA makes API request with JWT
│
4. Cloudflare validates JWT at edge
│
├── Invalid → 401 returned immediately (no backend hit)
│
└── Valid → Request forwarded via Cloudflare Tunnel
│
5. Request arrives at EKS Fargate (private, no public IP)
│
6. Python API processes request
│
├── Sync response → Direct DB/Cache query → Response
│
└── Async work → Publish to Kafka → Worker processes → Temporal for complex workflows
Dependencies and Constraints
AWS Dependencies
- EKS Fargate (compute)
- RDS PostgreSQL or Aurora (database)
- ElastiCache Redis or self-managed (cache)
- MSK (Kafka)
Cloudflare Dependencies
- Cloudflare Pages (PWA hosting)
- Cloudflare Access/Workers (JWT validation)
- Cloudflare Tunnel (backend connectivity)
Constraints
- No public backend endpoints — All traffic via Cloudflare Tunnel
- JWT validation at edge — Backend trusts Cloudflare-validated requests
- Regional considerations — Need to determine primary AWS region(s) based on farmer locations
Kubernetes Namespace Strategy
Services are organized into namespaces by domain:
┌─────────────────────────────────────────────────────────────────────────────┐
│ EKS NAMESPACE ORGANIZATION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ DOMAIN NAMESPACES │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ user-management │ │ access-mgmt │ │ surveys │ │
│ │ │ │ │ │ │ │
│ │ • user-bff │ │ • relationship- │ │ • surveys-bff │ │
│ │ • auth-service │ │ bff │ │ • survey-svc │ │
│ │ • profile-svc │ │ • invitation-svc│ │ • response-svc │ │
│ │ • prefs-svc │ │ • fga-svc │ │ • analytics-svc │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ │
│ │ payments │ │
│ │ │ │
│ │ • payments-bff │ │
│ │ • points-svc │ │
│ │ • payout-svc │ │
│ │ • provider-svc │ │
│ └─────────────────┘ │
│ │
│ PLATFORM NAMESPACES │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ platform-auth │ │ platform-authz │ │ platform- │ │
│ │ │ │ │ │ temporal │ │
│ │ • SuperTokens │ │ • OpenFGA │ │ • Temporal │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ platform- │ │ argocd │ │
│ │ unleash │ │ │ │
│ │ • Unleash │ │ • ArgoCD │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Namespace Benefits
- Isolation: Resource quotas, network policies per domain
- RBAC: Team access scoped to their namespace
- Organization: Clear service ownership
- Scaling: Independent scaling per domain
See 11-repository-structure.md for mono-repo folder-to-namespace mapping.
Open Questions
Last Updated: 2025-12-30