System Architecture

MindCradle is built on a modern, decoupled, and stateless cloud architecture. The system is split into three independent layers to ensure high availability, fast response times, and robust security.

+--------------------+        Vercel Reverse Proxy        +--------------------+
|  Vite React SPA    | ─────────────────────────────────> |   FastAPI Server   |
| (www.mindcradle)   | <─ (HTTPS / CORS / SameSite=None)  | (Google Cloud Run) |
+--------------------+                                    +--------------------+
                                                                    │
                                                                    ▼
                                                          +--------------------+
                                                          |  Supabase Database |
                                                          |    (PostgreSQL)    |
                                                          +--------------------+

Frontend

- Framework: React 18, Vite, Tailwind CSS v4, and React Router.
- Hosting: Vercel Edge.
- Routing: Client-side routing is handled via React Router. Relative `/api` requests are proxied dynamically to Cloud Run backend servers via Vercel configuration routes, preventing CORS issues.

Backend

- Framework: FastAPI (Python 3.11) served by Uvicorn.
- Hosting: Google Cloud Run (stateless container instance) with automatic scaling policies.
- AI Engine: Connects to OpenRouter for model execution and OpenAI for generating text embeddings. We implement asynchronous request queueing to keep response latencies minimal during peak traffic.

Database

- Provider: Supabase PostgreSQL.
- Extensions: `pgvector` for storing and performing cosine similarity searches on journal embeddings.
- Vector Search: Journal entries are processed using the text-embedding-3-small model. The resulting 1536-dimension vectors are indexed using HNSW indexes to allow sub-millisecond semantic search queries over years of text history.

Connection Pooling & Routing

We utilize connection pooling via Supabase connection pools to manage database connections efficiently, handling hundreds of concurrent users without query latency spikes. FastAPI maintains an active pool targeting our Supabase PostgreSQL instance. This design prevents database scaling limits and ensures optimal latency profiles for read and write queries. Our API router invokes OpenRouter with strict request timeouts. Conversations are processed asynchronously to ensure that temporary downstream latency from language models does not block the core API event loops.