How akshatsinghnayal/ragfastapi works
1. Overall shape
- This is a two-tier application: a React/Vite frontend and a FastAPI backend.
- The backend is not just an API gateway; it owns authentication, document ingestion, vector search, chat orchestration, and persistence.
- External managed services are part of the runtime architecture: PostgreSQL for relational state, Qdrant for vectors, and Google Gemini for embeddings and answers.
2. Frontend boundary
- The frontend is a client-side React app with pages for login, register, auth callback, dashboard, and document chat.
- It talks to the backend through a central Axios layer that handles JWT access tokens in memory and silent refresh using an httpOnly cookie.
- UI state is split between auth context, routed pages, and reusable components such as upload, message rendering, and source citation badges.
3. Backend entry and routing
- main.py is the FastAPI entrypoint and mounts the API surface.
- The backend is organized by feature router: auth, documents, and chat, plus health/debug endpoints.
- This structure suggests a clear separation between HTTP transport and business logic, with routers delegating into services.
4. Authentication subsystem
- Auth is JWT-based with short-lived access tokens and rotating refresh tokens stored in an httpOnly cookie.
- The auth flow supports both email/password and Google OAuth.
- auth/dependencies.py likely provides request-level identity/authorization checks used by documents and chat endpoints to enforce ownership.
5. User and persistence layer
- PostgreSQL holds the core relational entities: User, Document, and ChatMessage.
- SQLAlchemy async sessions and Alembic migrations indicate the backend treats the database as the source of truth for user accounts, document metadata, processing status, and conversation history.
- The alembic/versions folder shows schema evolution, including Google OAuth fields added after the initial schema.
6. Document ingestion pipeline
- PDF upload enters through the documents router, then the ingestion service parses the file with PyMuPDF.
- The document pipeline likely chunks text, generates embeddings, stores vectors in Qdrant, and updates processing status in PostgreSQL.
- The app intentionally does not persist uploaded PDFs on disk; storage is split between metadata in Postgres and chunk embeddings in Qdrant.
7. Vector search boundary
- vector/qdrant_client.py encapsulates all vector database access.
- Qdrant is the retrieval store for document chunks, using a fixed embedding dimension and cosine similarity.
- Searches are tenant-aware: retrieval is filtered by both document_id and user_id, preventing cross-user leakage and making ownership a hard boundary.
8. Chat / RAG flow
- The chat service orchestrates the RAG loop: receive a question, fetch recent chat context from Postgres, retrieve relevant chunks from Qdrant, and call Gemini for the answer.
- The response includes source citations, which the frontend renders through dedicated components.
- Conversation history is persisted, so the system supports per-document threaded chat rather than stateless Q&A.
9. Google integration
- services/google_auth.py handles Google Sign-In and token verification.
- Google OAuth is used for login, while Gemini provides both embeddings and generation.
- These are separate integrations with different trust boundaries: OAuth authenticates the user, Gemini powers content understanding and response generation.
10. Shared backend utilities
- utils/security.py and utils/errors.py centralize cross-cutting concerns such as password hashing, token/cookie handling, and structured API errors.
- schemas/ defines request/response contracts, keeping transport shapes separate from database models.
- config.py and database.py form the backend foundation layer: environment-driven settings plus async DB wiring.
11. Frontend UX and state flow
- The frontend is optimized for a document-chat workflow: upload, wait for processing, select a document, then chat against it.
- The dashboard polls for document processing updates, while the chat UI updates optimistically and renders markdown-heavy, citation-rich responses.
- Access control on the client is handled by route guards, but real authorization is enforced on the backend.
12. Operational/deployment boundaries
- The intended deployment splits the system into Render for backend, Vercel for frontend, and Qdrant Cloud for vectors.
- Environment variables define the integration points: backend URL, frontend URL, database URL, Gemini key, OAuth credentials, and Qdrant credentials.
- This architecture depends on CORS, cookie settings, and OAuth redirect configuration lining up across those three runtime surfaces.
13. What to draw in an architecture diagram
- Draw the frontend as the user entry point, calling the FastAPI backend.
- Inside the backend, show three main business flows: auth, document ingestion, and chat/RAG.
- Show Postgres as the system of record, Qdrant as the retrieval index, and Google services as external dependencies for OAuth and LLM/embedding calls.
Main entry points: main.py FastAPI app · database.py DB wiring · auth/service.py Auth logic · chat/service.py RAG service
Components 23
Frontend
React/Vite client for login, dashboard, upload, and document chat
- React app · Client entry and route composition
frontend/src/App.jsx - API client · Central HTTP client with token handling and refresh flow
frontend/src/api/axios.js - Auth state · In-memory auth state and session bootstrap
frontend/src/context/AuthContext.jsx - Route guard · Protects authenticated routes
frontend/src/components/ProtectedRoute.jsx - Pages · Login, register, callback, dashboard, and chat screens
frontend/src/pages/Dashboard.jsx - UI widgets · Upload, messages, citations, and document cards
frontend/src/components/UploadZone.jsx
Backend
FastAPI app with auth, ingestion, and RAG orchestration
- FastAPI app · API bootstrap and route mounting
backend/main.py - Auth API · Login, register, refresh, and OAuth endpoints
backend/app/auth/router.py - Auth logic · JWT, refresh tokens, and Google sign-in handling
backend/app/auth/service.py - Documents API · Upload and document status endpoints
backend/app/documents/router.py - Ingestion service · Parses uploads, chunks content, and tracks processing
backend/app/documents/service.py - PDF ingest · Text extraction and chunk preparation
backend/app/documents/ingestion.py - Chat API · Document chat and history endpoints
backend/app/chat/router.py - RAG service · Retrieval-augmented answer orchestration
backend/app/chat/service.py - Data models · User, document, and chat message entities
backend/app/models/models.py - DB wiring · Session and engine configuration
backend/app/database.py - Config · Environment-driven runtime settings
backend/app/config.py - Security utils · Password hashing, JWT, and cookie utilities
backend/app/utils/security.py - Vector index · Tenant-aware chunk storage and retrieval
backend/app/vector/qdrant_client.py - Google auth · Google Sign-In verification and token checks
backend/app/services/google_auth.py
External services
Managed dependencies for persistence, vectors, and Google integrations
- PostgreSQL · Relational system of record
- Qdrant · Chunk embeddings and similarity search
- Google APIs · User authentication and LLM/embedding provider
Connections 27
- React app → API client: HTTP calls · All backend requests go through the shared client
- React app → Auth state: session state · App wraps routes with auth context
- Auth state → Route guard: protects · Authenticated routes are gated on client state
- React app → Pages: routes · Login, register, callback, dashboard, and chat views
- Pages → UI widgets: renders · Pages compose upload and chat UI pieces
- API client → FastAPI app: REST API · Frontend talks to the FastAPI backend
- FastAPI app → Auth API: mounts · Main app exposes auth routes
- FastAPI app → Documents API: mounts · Main app exposes document routes
- FastAPI app → Chat API: mounts · Main app exposes chat routes
- Auth API → Auth logic: delegates · HTTP auth endpoints call auth logic
- Documents API → Ingestion service: delegates · Document endpoints call ingestion logic
- Chat API → RAG service: delegates · Chat endpoints call RAG orchestration
- Auth logic → Security utils: uses · Token and password helpers support auth flow
- Auth logic → Google auth: verifies · Google OAuth login is validated here
- Auth logic → Google APIs: OAuth · Google identity provider
- Ingestion service → PDF ingest: parses · Uploads are extracted and chunked
- Ingestion service → DB wiring: stores status · Processing state and metadata persist in Postgres
- PDF ingest → Vector index: indexes chunks · Embeddings are written for retrieval
- RAG service → DB wiring: loads history · Recent messages and ownership data come from Postgres
- RAG service → Vector index: retrieves context · Relevant chunks are fetched from the vector index
- RAG service → Google APIs: Gemini calls · Answer generation and embeddings provider
- Vector index → Qdrant: vector ops · Qdrant stores and searches document chunks
- DB wiring → PostgreSQL: async SQL · Relational persistence layer
- Data models → DB wiring: mapped by · ORM models are backed by the async database layer
- Config → FastAPI app: configures · Runtime settings feed app startup
- Config → DB wiring: settings · Database and environment configuration
- Security utils → Auth API: auth primitives · Routers use security helpers for tokens and cookies