Architecture

System Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Amplify    │────▶│   Traefik    │────▶│   FastAPI    │
│  (Frontend)  │     │ (Reverse Proxy)│    │  (Backend)   │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                │
                    ┌───────────────────────────┤
                    ▼              ▼             ▼
              ┌──────────┐  ┌──────────┐  ┌──────────┐
              │   RDS    │  │  Valkey  │  │    S3    │
              │(PostgreSQL)│ │ (Cache)  │  │ (Images) │
              └──────────┘  └──────────┘  └──────────┘

Request Flow

1. Frontend (React on Amplify) makes API calls to api.tiny-agents.kovacova.ca
2. Traefik terminates TLS and routes to the correct backend service
3. FastAPI handles the request, authenticating via Better-Auth JWTs
4. PostgreSQL (RDS) stores all data; pgvector handles embedding similarity search
5. Valkey caches frequently accessed data (knowledge base, sessions)
6. S3 stores meal images

Database Design

Two databases on the same RDS instance:

• mealpal — main application data (meals, chat, embeddings)
• auth — Better-Auth tables (users, sessions, accounts)

The mealpal database uses pgvector for RAG embeddings (1536-dimensional OpenAI vectors).

Deployment

Blue-green zero-downtime deploys via ./deploy.sh:

1. Build new container image
2. Start new container alongside the old one
3. Health check the new container
4. Update Traefik routing to the new container
5. Drain and stop the old container

All infrastructure runs in ca-central-1 for Canadian data residency.