# vattey12dec/pdf-brain-mobile-app architecture

> Architecture diagram of the GitHub repository vattey12dec/pdf-brain-mobile-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vattey12dec/pdf-brain-mobile-app
- Repository: https://github.com/vattey12dec/pdf-brain-mobile-app

## Overview

PDF Brain accepts authenticated PDF uploads, extracts and chunks their text, indexes embeddings, then retrieves relevant passages to produce cited Gemini answers. The backend also exposes document management, chat-history, and conversation operations. The README describes a Flutter client, but this tree contains only native platform scaffolding, not its application UI; client requests are therefore represented at the API boundary. Edges reflect sampled backend calls and README-documented integrations; unsampled details are omitted.

Main entry points: [`backend/app/routers/documents.py`](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/documents.py) (Document API), [`backend/app/routers/chat.py`](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/chat.py) (Chat API), [`backend/app/main.py`](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/core/database.py`](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/database.py) (SQL database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["JWT authentication<br/>[security.py]"]
  node_schemas["API schemas<br/>[api_schemas.py]"]
  node_config["Application settings<br/>[config.py]"]
end

subgraph group_ingest["PDF ingestion"]
  node_documents["Document API<br/>[documents.py]"]
  node_pdf["PDF validation and extraction<br/>[pdf_service.py]"]
  node_chunking["Text chunking"]
  node_vectors["Vector service<br/>[vector_service.py]"]
end

subgraph group_qa["Question answering"]
  node_chat["Chat API<br/>[chat.py]"]
  node_rag["RAG answer generation<br/>[rag_service.py]"]
  node_conversations["Conversation API<br/>[conversations.py]"]
end

subgraph group_persistence["Persistence"]
  node_chromadb[("ChromaDB index")]
  node_models["Persistence models<br/>[db_models.py]"]
  node_database["SQL database access<br/>[database.py]"]
  node_sqlstore[("SQLite or SQL store")]
end

node_user(("User"))
node_supabase["Supabase Auth"]
node_gemini["Gemini API"]

node_user -->|"sends requests"| node_api
node_api -->|"registers routes"| node_documents
node_api -->|"registers routes"| node_chat
node_api -->|"registers routes"| node_conversations
node_documents -->|"requires identity"| node_auth
node_chat -->|"requires identity"| node_auth
node_conversations -->|"requires identity"| node_auth
node_auth -->|"verifies token"| node_supabase
node_documents -->|"validates and extracts"| node_pdf
node_documents -->|"creates chunks"| node_chunking
node_documents -->|"indexes chunks"| node_vectors
node_chunking -->|"consumes pages"| node_pdf
node_vectors -->|"queries and writes"| node_chromadb
node_chat -->|"retrieves chunks"| node_vectors
node_chat -->|"requests answer"| node_rag
node_rag -->|"generates answer"| node_gemini
node_chat -->|"stores chat history"| node_database
node_conversations -->|"manages conversations"| node_database
node_database -->|"registers tables"| node_models
node_database -->|"reads and writes"| node_sqlstore
node_api -->|"initializes storage"| node_database
node_documents -->|"reads and updates"| node_models
node_documents -->|"validates responses"| node_schemas
node_chat -->|"uses request and response types"| node_schemas
node_conversations -->|"reads and updates"| node_models
node_config -.->|"configures models"| node_gemini

click node_api "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/main.py"
click node_auth "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/security.py"
click node_documents "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/documents.py"
click node_pdf "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/pdf_service.py"
click node_chunking "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/chunking_service.py"
click node_vectors "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/vector_service.py"
click node_chat "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/chat.py"
click node_rag "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/rag_service.py"
click node_conversations "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/conversations.py"
click node_models "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/models/db_models.py"
click node_database "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/database.py"
click node_schemas "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/schemas/api_schemas.py"
click node_config "https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/config.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_api,node_auth,node_schemas,node_config,node_user toneBlue
class node_documents,node_pdf,node_chunking,node_vectors toneAmber
class node_chat,node_rag,node_conversations,node_gemini toneMint
class node_chromadb,node_models,node_database,node_sqlstore toneRose
class node_supabase toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/main.py): `backend/app/main.py`
- [JWT authentication](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [API schemas](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/schemas/api_schemas.py): `backend/app/schemas/api_schemas.py`
- [Application settings](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### PDF ingestion

- [Document API](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/documents.py): `backend/app/routers/documents.py`
- [PDF validation and extraction](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Text chunking](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/chunking_service.py): `backend/app/services/chunking_service.py`
- [Vector service](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/vector_service.py): `backend/app/services/vector_service.py`

### Question answering

- [Chat API](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [RAG answer generation](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Conversation API](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/routers/conversations.py): `backend/app/routers/conversations.py`

### Persistence

- **ChromaDB index**
- [Persistence models](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/models/db_models.py): `backend/app/models/db_models.py`
- [SQL database access](https://github.com/vattey12dec/pdf-brain-mobile-app/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **SQLite or SQL store**

### Other components

- **User**
- **Supabase Auth**
- **Gemini API**

## Connections

- User → FastAPI application: sends requests
- FastAPI application → Document API: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Chat API: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Conversation API: registers routes (evidence: `backend/app/main.py`)
- Document API → JWT authentication: requires identity (evidence: `backend/app/routers/documents.py`)
- Chat API → JWT authentication: requires identity (evidence: `backend/app/routers/chat.py`)
- Conversation API → JWT authentication: requires identity (evidence: `backend/app/routers/conversations.py`)
- JWT authentication → Supabase Auth: verifies token (evidence: `backend/app/core/security.py`)
- Document API → PDF validation and extraction: validates and extracts (evidence: `backend/app/routers/documents.py`)
- Document API → Text chunking: creates chunks (evidence: `backend/app/routers/documents.py`)
- Document API → Vector service: indexes chunks (evidence: `backend/app/routers/documents.py`)
- Text chunking → PDF validation and extraction: consumes pages (evidence: `backend/app/services/chunking_service.py`)
- Vector service → ChromaDB index: queries and writes (evidence: `backend/app/services/vector_service.py`)
- Chat API → Vector service: retrieves chunks (evidence: `backend/app/routers/chat.py`)
- Chat API → RAG answer generation: requests answer (evidence: `backend/app/routers/chat.py`)
- RAG answer generation → Gemini API: generates answer (evidence: `backend/app/services/rag_service.py`)
- Chat API → SQL database access: stores chat history (evidence: `backend/app/routers/chat.py`)
- Conversation API → SQL database access: manages conversations (evidence: `backend/app/routers/conversations.py`)
- SQL database access → Persistence models: registers tables (evidence: `backend/app/core/database.py`)
- SQL database access → SQLite or SQL store: reads and writes (evidence: `backend/app/core/database.py`)
- FastAPI application → SQL database access: initializes storage (evidence: `backend/app/main.py`)
- Document API → Persistence models: reads and updates (evidence: `backend/app/routers/documents.py`)
- Document API → API schemas: validates responses (evidence: `backend/app/routers/documents.py`)
- Chat API → API schemas: uses request and response types (evidence: `backend/app/routers/chat.py`)
- Conversation API → Persistence models: reads and updates (evidence: `backend/app/routers/conversations.py`)
- Application settings → Gemini API: configures models
