System Architecture Overview

EpsimoAI is a multi-tenant AI assistant platform built on FastAPI, LangChain/LangGraph, and Next.js. It runs on AWS ECS Fargate with PostgreSQL (RDS) as the primary data store.

C4 System Context Diagram

graph TB Browser["Browser<br/>(User)"] subgraph AWS["AWS (us-east-1)"] ALB["Application Load Balancer"] subgraph ECS["ECS Fargate Cluster"] Frontend["Frontend Service<br/>Next.js · port 3000<br/>(epsimo-frontend)"] Backend["Backend Service<br/>FastAPI · port 8000<br/>(epsimoai-backend-604b)"] end RDS["RDS PostgreSQL<br/>pgvector extension"] Secrets["AWS Secrets Manager<br/>epsimoai-backend/secrets-s7LP8T"] ECR["ECR<br/>Docker Images"] end OpenAI["OpenAI API<br/>GPT-4o, GPT-4o-mini, GPT-5 nano"] Anthropic["Anthropic API<br/>Claude 3.5/3.7 Sonnet, Opus, Haiku"] Groq["Groq API<br/>Llama, Mixtral, DeepSeek"] DeepSeek["DeepSeek API"] Grok["Grok API (xAI)"] Stripe["Stripe API<br/>Payments"] SMTP["SMTP<br/>smtp.hostinger.com:465"] Google["Google OAuth"] Browser --> ALB ALB --> Frontend ALB --> Backend Frontend -.->|NEXT_PUBLIC_API_URL| Backend Backend --> RDS Backend --> Secrets Backend --> OpenAI Backend --> Anthropic Backend --> Groq Backend --> DeepSeek Backend --> Grok Backend --> Stripe Backend --> SMTP Backend --> Google ECR -.->|deploy| ECS

Component Descriptions

Component Technology Purpose
Frontend Next.js 14+, React, TypeScript, Tailwind Dashboard UI for managing projects, assistants, threads
Backend FastAPI, Python 3.11+, LangChain, LangGraph REST API, AI orchestration, streaming, auth
PostgreSQL RDS, pgvector extension Users, projects, assistants, threads, checkpoints, vector embeddings
Secrets Manager AWS Secrets Manager Stores API keys, DB password, JWT keys, OAuth secrets
ALB AWS Application Load Balancer TLS termination, routing to ECS tasks
ECR AWS Elastic Container Registry Docker image storage for CI/CD

Google OAuth Login Flow

sequenceDiagram participant B as Browser participant F as Frontend participant BE as Backend (FastAPI) participant G as Google OAuth B->>F: Click "Sign in with Google" F->>BE: GET /auth/google/login BE->>G: Redirect to Google consent screen G->>B: Show consent UI B->>G: Approve G->>BE: GET /auth/google/callback?code=... BE->>G: Exchange code for user info G-->>BE: Return email, name, picture BE->>BE: Find or create user, generate JWT (HS256, 30d) BE->>F: Redirect to FRONTEND_URL/auth-callback?token=JWT F->>F: Store JWT in localStorage F->>B: Render dashboard

Streaming Chat Run Flow

sequenceDiagram participant F as Frontend participant BE as Backend (FastAPI) participant LG as LangGraph Agent participant LLM as LLM Provider (OpenAI/Anthropic) participant VS as Vector Store (pgvector) F->>BE: POST /runs/stream {assistant_id, thread_id, messages} BE->>BE: Load assistant config, resolve tools BE->>LG: Invoke agent graph with messages + config loop Agent Loop LG->>LLM: Send messages (streaming) LLM-->>LG: Stream token chunks LG-->>BE: Yield events (tokens, tool calls) opt Tool Call (e.g. retrieval) LG->>VS: Similarity search VS-->>LG: Return documents LG->>LLM: Send tool result LLM-->>LG: Continue streaming end end BE-->>F: SSE stream (data: {event, data}\n\n) BE->>BE: Save checkpoint to PostgreSQL F->>F: Render streamed response in real-time

Deployment Details