Architecture
System Architecture Overview
FreshHome is built on a cloud-native, microservices architecture designed for high availability, horizontal scalability, and rapid deployment.
Cloud Infrastructure
Primary Cloud Provider: AWS
Deployed across 3 AWS regions (eu-west-1, us-east-1, ap-southeast-1) with automatic failover and load balancing for global resilience.
⚙️ Compute: AWS ECS (Fargate) for containerised microservices, with auto-scaling groups
🗄️ Primary Database: AWS RDS PostgreSQL (Multi-AZ) for transactional data
📄 Document Store: MongoDB Atlas for flexible menu and review data
⚡ Cache: Redis (ElastiCache) for sessions, rate limiting, and real-time state
📦 Object Storage: AWS S3 + CloudFront CDN for all media assets
📨 Messaging: AWS SQS + SNS for async event-driven communication
Technology
Technology Stack
📱 Mobile Apps
🍎 iOS: React Native + Swift modules
🤖 Android: React Native + Kotlin modules
🗺️ Maps: Google Maps SDK
🔔 Push: Firebase Cloud Messaging
🌐 Web Frontend
⚛️ React.js (customer web app)
📊 React.js (provider dashboard)
🎨 Tailwind CSS + custom design system
🔄 React Query for data fetching
⚙️ Backend API
🟢 Node.js + Express.js (REST API)
🔌 WebSocket (Socket.io) for real-time
🐳 Docker containers, AWS ECS
📋 OpenAPI 3.0 spec
🔗 Integrations
💳 Stripe (payments)
🗺️ Google Maps Platform
📱 Twilio (SMS)
📧 SendGrid (email)
API Reference
Authentication Endpoints
All API requests require a valid JWT Bearer token (except registration and login). Tokens expire after 24 hours. Use refresh tokens for seamless re-authentication.
POST/api/v1/auth/registerRegister a new customer or provider
POST/api/v1/auth/loginLogin and receive access + refresh tokens
POST/api/v1/auth/refreshExchange refresh token for new access token
POST/api/v1/auth/logoutInvalidate current session tokens
POST/api/v1/auth/verify-emailVerify email with OTP code
POST/api/v1/auth/forgot-passwordInitiate password reset flow
POST/api/v1/auth/reset-passwordComplete password reset with token
Customer Endpoints
Meals & Discovery
GET/api/v1/mealsList available meals (with filters)
GET/api/v1/meals/:idGet meal detail, ingredients, allergens
GET/api/v1/providersList providers near location
GET/api/v1/providers/:idGet provider profile and menu
Orders
POST/api/v1/ordersPlace a new order
GET/api/v1/orders/:idGet order status and details
GET/api/v1/ordersGet customer order history
DEL/api/v1/orders/:idCancel order (within window)
GET/api/v1/orders/:id/trackingGet real-time tracking data
Ratings
POST/api/v1/orders/:id/reviewSubmit rating and review for an order
GET/api/v1/providers/:id/reviewsList reviews for a provider
Provider Endpoints
Menu Management
GET/api/v1/provider/mealsList provider's meal listings
POST/api/v1/provider/mealsCreate a new meal listing
PUT/api/v1/provider/meals/:idUpdate meal details or availability
DEL/api/v1/provider/meals/:idRemove a meal listing
Order Management
GET/api/v1/provider/ordersGet incoming and active orders
PUT/api/v1/provider/orders/:id/acceptAccept an incoming order
PUT/api/v1/provider/orders/:id/declineDecline an incoming order
PUT/api/v1/provider/orders/:id/statusUpdate order preparation status
Analytics & Earnings
GET/api/v1/provider/earningsGet earnings summary (daily/weekly/monthly)
GET/api/v1/provider/analyticsGet performance metrics and insights
GET/api/v1/provider/payoutsGet payout history and status
Payment Endpoints
POST/api/v1/payments/intentCreate Stripe PaymentIntent for order
POST/api/v1/payments/confirmConfirm payment after 3DS auth
POST/api/v1/payments/refundInitiate a refund for an order
GET/api/v1/wallet/balanceGet FreshHome wallet balance
POST/api/v1/wallet/topupTop up FreshHome wallet
POST/api/v1/payments/webhookStripe webhook handler (internal)
Notification Endpoints
POST/api/v1/notifications/tokenRegister device push notification token
GET/api/v1/notificationsGet user notification history
PUT/api/v1/notifications/preferencesUpdate notification preferences
GET/api/v1/tracking/wsWebSocket endpoint for live order tracking
Security
Encryption & Authentication
🔐 Transport Security
All API communications use TLS 1.3. HTTP connections are automatically redirected to HTTPS. HSTS headers enforced with a max-age of 31536000 seconds.
🔑 Authentication
JWT tokens signed with RS256 (RSA + SHA-256). Access tokens expire after 24 hours. Refresh tokens expire after 30 days. Token rotation on each refresh.
💳 Payment Security
PCI DSS Level 1 compliant via Stripe. Card data is tokenised at the client — raw card numbers never reach FreshHome servers. 3D Secure 2.0 enforced for high-value transactions.
Compliance
🇪🇺
GDPR
Full General Data Protection Regulation compliance for EU/UK customers. Right to access, correct, delete personal data on request.
💳
PCI DSS
Level 1 PCI DSS compliance through our payment processor. Annual audits and quarterly scans by an Approved Scanning Vendor.
🍽️
Food Safety
Provider compliance with local health department regulations, EU Food Hygiene Regulations, and FCD 852/2004 standards.
🛡️
Data Residency
EU customer data stored in eu-west-1 (Ireland). Data transfer outside EU governed by Standard Contractual Clauses.
Operations
Scalability
📈 Auto-scaling: ECS tasks scale based on CPU/memory utilisation. Min 2, Max 50 instances per service.
🗄️ Database: Read replicas for analytics queries. Connection pooling via PgBouncer.
⚡ Caching: Redis caches menu data (TTL 5 min), provider profiles (TTL 10 min), and static content.
🌍 CDN: CloudFront serves all images and static assets with global edge caching (TTL 24h).
⚖️ Load balancing: AWS ALB with health checks and sticky sessions for WebSocket connections.
📊 Monitoring: Datadog APM, CloudWatch metrics, PagerDuty alerting. 99.9% uptime SLA.
Integrations & Dependencies
| Service | Provider | Purpose |
|---|
| Payments | Stripe | Card processing, provider payouts, refunds, webhooks |
| Maps & Location | Google Maps Platform | Geocoding, pickup point mapping, provider coverage areas |
| SMS | Twilio | OTP verification, order status SMS |
| Email | SendGrid | Transactional emails, receipts, marketing |
| Push Notifications | Firebase Cloud Messaging | iOS and Android push notifications |
| Analytics | Mixpanel + Datadog | User analytics, performance monitoring |
| Background Checks | Checkr | Provider identity and DBS checks |
| Cloud Storage | AWS S3 | Meal photos, documents, reports |
Deployment
FreshHome uses a GitOps continuous delivery pipeline.
// CI/CD PIPELINE
[Developer Push] → [GitHub PR] → [CI: Jest Tests + ESLint]
↓ ↓
[Code Review] [E2E Tests: Cypress / Playwright]
↓ ↓
[Merge to main] ←────────── [All Checks Pass]
↓
[Docker Build + Push to ECR]
↓
[Deploy to Staging (ECS)]
↓
[Smoke Tests + Health Checks]
↓
[Blue/Green Deploy to Production]
↓
[Datadog Monitors Watch for Regressions]
↓
[Automatic Rollback if Error Rate Spikes]