# akshatsinghnayal/ragfastapi architecture

> Architecture diagram of the GitHub repository akshatsinghnayal/ragfastapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshatsinghnayal/ragfastapi
- Repository: https://github.com/akshatsinghnayal/ragfastapi

## Overview

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: [`backend/main.py`](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/main.py) (FastAPI app), [`backend/app/database.py`](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/database.py) (DB wiring), [`backend/app/auth/service.py`](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/auth/service.py) (Auth logic), [`backend/app/chat/service.py`](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/chat/service.py) (RAG service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["React app<br/>SPA<br/>[App.jsx]"]
  node_fe_api["API client<br/>Axios layer<br/>[axios.js]"]
  node_fe_auth["Auth state<br/>Context<br/>[AuthContext.jsx]"]
  node_fe_guard["Route guard<br/>UI gate<br/>[ProtectedRoute.jsx]"]
  node_fe_pages["Pages<br/>Routes<br/>[Dashboard.jsx]"]
  node_fe_widgets["UI widgets<br/>Components<br/>[UploadZone.jsx]"]
end

subgraph group_backend["Backend"]
  node_be_main["FastAPI app<br/>Entrypoint<br/>[main.py]"]
  node_be_auth_route["Auth API<br/>Router<br/>[router.py]"]
  node_be_auth_service["Auth logic<br/>[service.py]"]
  node_be_docs_route["Documents API<br/>Router<br/>[router.py]"]
  node_be_docs_service["Ingestion service<br/>[service.py]"]
  node_be_ingest["PDF ingest<br/>Pipeline<br/>[ingestion.py]"]
  node_be_chat_route["Chat API<br/>Router<br/>[router.py]"]
  node_be_chat_service["RAG service<br/>[service.py]"]
  node_be_models["Data models<br/>SQLAlchemy<br/>[models.py]"]
  node_be_db["DB wiring<br/>Async SQLAlchemy<br/>[database.py]"]
  node_be_cfg["Config<br/>Settings<br/>[config.py]"]
  node_be_sec["Security utils<br/>Helpers<br/>[security.py]"]
  node_be_qdrant["Vector index<br/>Qdrant client<br/>[qdrant_client.py]"]
  node_be_google["Google auth<br/>OAuth helper<br/>[google_auth.py]"]
end

subgraph group_external["External services"]
  node_ext_pg[("PostgreSQL<br/>Database")]
  node_ext_qdrant[("Qdrant<br/>Vector DB")]
  node_ext_google(("Google APIs<br/>OAuth + Gemini"))
end

node_fe_app -->|"HTTP calls"| node_fe_api
node_fe_app -->|"session state"| node_fe_auth
node_fe_auth -->|"protects"| node_fe_guard
node_fe_app -->|"routes"| node_fe_pages
node_fe_pages -->|"renders"| node_fe_widgets
node_fe_api -->|"REST API"| node_be_main
node_be_main -->|"mounts"| node_be_auth_route
node_be_main -->|"mounts"| node_be_docs_route
node_be_main -->|"mounts"| node_be_chat_route
node_be_auth_route -->|"delegates"| node_be_auth_service
node_be_docs_route -->|"delegates"| node_be_docs_service
node_be_chat_route -->|"delegates"| node_be_chat_service
node_be_auth_service -->|"uses"| node_be_sec
node_be_auth_service -->|"verifies"| node_be_google
node_be_auth_service -->|"OAuth"| node_ext_google
node_be_docs_service -->|"parses"| node_be_ingest
node_be_docs_service -->|"stores status"| node_be_db
node_be_ingest -->|"indexes chunks"| node_be_qdrant
node_be_chat_service -->|"loads history"| node_be_db
node_be_chat_service -->|"retrieves context"| node_be_qdrant
node_be_chat_service -->|"Gemini calls"| node_ext_google
node_be_qdrant -->|"vector ops"| node_ext_qdrant
node_be_db -->|"async SQL"| node_ext_pg
node_be_models -->|"mapped by"| node_be_db
node_be_cfg -->|"configures"| node_be_main
node_be_cfg -->|"settings"| node_be_db
node_be_sec -->|"auth primitives"| node_be_auth_route

click node_fe_app "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/App.jsx"
click node_fe_api "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/api/axios.js"
click node_fe_auth "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/context/AuthContext.jsx"
click node_fe_guard "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_fe_pages "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/pages/Dashboard.jsx"
click node_fe_widgets "https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/components/UploadZone.jsx"
click node_be_main "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/main.py"
click node_be_auth_route "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/auth/router.py"
click node_be_auth_service "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/auth/service.py"
click node_be_docs_route "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/router.py"
click node_be_docs_service "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/service.py"
click node_be_ingest "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/ingestion.py"
click node_be_chat_route "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/chat/router.py"
click node_be_chat_service "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/chat/service.py"
click node_be_models "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/models/models.py"
click node_be_db "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/database.py"
click node_be_cfg "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/config.py"
click node_be_sec "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/utils/security.py"
click node_be_qdrant "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/vector/qdrant_client.py"
click node_be_google "https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/services/google_auth.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fe_app,node_fe_api,node_fe_auth,node_fe_guard,node_fe_pages,node_fe_widgets toneBlue
class node_be_main,node_be_auth_route,node_be_auth_service,node_be_docs_route,node_be_docs_service,node_be_ingest,node_be_chat_route,node_be_chat_service,node_be_models,node_be_db,node_be_cfg,node_be_sec,node_be_qdrant,node_be_google toneAmber
class node_ext_pg,node_ext_qdrant,node_ext_google toneMint
```

## Components

### Frontend

React/Vite client for login, dashboard, upload, and document chat

- [React app](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/App.jsx): SPA · Client entry and route composition · `frontend/src/App.jsx`
- [API client](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/api/axios.js): Axios layer · Central HTTP client with token handling and refresh flow · `frontend/src/api/axios.js`
- [Auth state](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/context/AuthContext.jsx): Context · In-memory auth state and session bootstrap · `frontend/src/context/AuthContext.jsx`
- [Route guard](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/components/ProtectedRoute.jsx): UI gate · Protects authenticated routes · `frontend/src/components/ProtectedRoute.jsx`
- [Pages](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/pages/Dashboard.jsx): Routes · Login, register, callback, dashboard, and chat screens · `frontend/src/pages/Dashboard.jsx`
- [UI widgets](https://github.com/akshatsinghnayal/ragfastapi/blob/main/frontend/src/components/UploadZone.jsx): Components · Upload, messages, citations, and document cards · `frontend/src/components/UploadZone.jsx`

### Backend

FastAPI app with auth, ingestion, and RAG orchestration

- [FastAPI app](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/main.py): Entrypoint · API bootstrap and route mounting · `backend/main.py`
- [Auth API](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/auth/router.py): Router · Login, register, refresh, and OAuth endpoints · `backend/app/auth/router.py`
- [Auth logic](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/auth/service.py): Service · JWT, refresh tokens, and Google sign-in handling · `backend/app/auth/service.py`
- [Documents API](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/router.py): Router · Upload and document status endpoints · `backend/app/documents/router.py`
- [Ingestion service](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/service.py): Service · Parses uploads, chunks content, and tracks processing · `backend/app/documents/service.py`
- [PDF ingest](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/documents/ingestion.py): Pipeline · Text extraction and chunk preparation · `backend/app/documents/ingestion.py`
- [Chat API](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/chat/router.py): Router · Document chat and history endpoints · `backend/app/chat/router.py`
- [RAG service](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/chat/service.py): Service · Retrieval-augmented answer orchestration · `backend/app/chat/service.py`
- [Data models](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/models/models.py): SQLAlchemy · User, document, and chat message entities · `backend/app/models/models.py`
- [DB wiring](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/database.py): Async SQLAlchemy · Session and engine configuration · `backend/app/database.py`
- [Config](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/config.py): Settings · Environment-driven runtime settings · `backend/app/config.py`
- [Security utils](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/utils/security.py): Helpers · Password hashing, JWT, and cookie utilities · `backend/app/utils/security.py`
- [Vector index](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/vector/qdrant_client.py): Qdrant client · Tenant-aware chunk storage and retrieval · `backend/app/vector/qdrant_client.py`
- [Google auth](https://github.com/akshatsinghnayal/ragfastapi/blob/main/backend/app/services/google_auth.py): OAuth helper · Google Sign-In verification and token checks · `backend/app/services/google_auth.py`

### External services

Managed dependencies for persistence, vectors, and Google integrations

- **PostgreSQL**: Database · Relational system of record
- **Qdrant**: Vector DB · Chunk embeddings and similarity search
- **Google APIs**: OAuth + Gemini · User authentication and LLM/embedding provider

## Connections

- 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
