# krisnasetyadi/doculens-server architecture

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

- Interactive diagram: https://gitdiagram.com/krisnasetyadi/doculens-server
- Repository: https://github.com/krisnasetyadi/doculens-server

## Overview

DocuLens is a FastAPI document and chat Q&A service: users upload or connect sources, the backend indexes searchable content, and hybrid queries retrieve evidence from PDFs, PostgreSQL, and chat logs before producing an LLM answer. The graph also captures the separate agnostic multi-source RAG pipeline and documented API capabilities such as collection management, authentication, and persisted chat sessions. Some route and processor implementations were not sampled, so their links reflect README claims or explicit entry-point wiring rather than inferred internal call chains.

Main entry points: [`main.py`](https://github.com/krisnasetyadi/doculens-server/blob/main/main.py) (FastAPI app), [`router/hybrid.py`](https://github.com/krisnasetyadi/doculens-server/blob/main/router/hybrid.py) (Hybrid query), [`chat_ingest.py`](https://github.com/krisnasetyadi/doculens-server/blob/main/chat_ingest.py) (Chat indexing), [`agnostic/pipeline.py`](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/pipeline.py) (Agnostic RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Accounts"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_sessions["Chat sessions<br/>[sessions.py]"]
end

subgraph group_sources["Source Ingestion"]
  node_pdf_upload["PDF upload<br/>[upload.py]"]
  node_pdf_collections["PDF collections<br/>[collections.py]"]
  node_pdf_processing["PDF processing<br/>[processor.py]"]
  node_chat_routes["Chat imports<br/>[chat.py]"]
  node_chat_parser["Chat parsing<br/>[chat_parser.py]"]
  node_chat_ingest["Chat indexing<br/>[chat_ingest.py]"]
  node_telegram["Telegram sync<br/>[telegram.py]"]
  node_db_connections["DB connections"]
end

subgraph group_rag["Retrieval and Answers"]
  node_hybrid["Hybrid query<br/>[hybrid.py]"]
  node_agnostic_pipeline["Agnostic RAG<br/>[pipeline.py]"]
  node_source_adapters["Source adapters<br/>[adapters.py]"]
  node_indexer["Runtime indexing<br/>[indexer.py]"]
  node_retriever["Chunk retrieval<br/>[retriever.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
  node_db_search["Database search<br/>[database.py]"]
  node_answer["Answer with sources"]
end

subgraph group_state["Persistence"]
  node_storage["Storage wrapper<br/>[storage.py]"]
  node_app_db[("App database<br/>[app_db.py]")]
  node_vector_indices[("Vector indices")]
end

subgraph group_integrations["External Services"]
  node_postgres[("PostgreSQL")]
  node_object_storage[("Supabase storage")]
  node_llm["LLM providers"]
end

node_user(("User"))

node_user -->|"sends requests"| node_api
node_api -->|"dispatches auth"| node_auth
node_api -->|"dispatches upload"| node_pdf_upload
node_api -->|"dispatches collection requests"| node_pdf_collections
node_api -->|"dispatches queries"| node_hybrid
node_api -->|"dispatches chat imports"| node_chat_routes
node_api -->|"dispatches Telegram routes"| node_telegram
node_api -->|"dispatches session requests"| node_sessions
node_api -->|"dispatches connection requests"| node_db_connections
node_pdf_upload -->|"processes PDFs"| node_pdf_processing
node_pdf_processing -->|"builds index"| node_vector_indices
node_pdf_collections -->|"manages collection files"| node_storage
node_chat_routes -->|"parses exports"| node_chat_parser
node_chat_routes -->|"ingests messages"| node_chat_ingest
node_telegram -->|"ingests synced messages"| node_chat_ingest
node_chat_ingest -->|"saves chat index"| node_vector_indices
node_chat_ingest -->|"persists chat data"| node_storage
node_hybrid -->|"searches PDF collections"| node_pdf_processing
node_hybrid -->|"searches database"| node_db_search
node_hybrid -->|"searches chat collections"| node_chat_ingest
node_db_search -->|"queries"| node_postgres
node_db_connections -->|"stores connection records"| node_app_db
node_db_connections -->|"inspects external schema"| node_postgres
node_agnostic_pipeline -->|"loads source data"| node_source_adapters
node_agnostic_pipeline -->|"builds index"| node_indexer
node_agnostic_pipeline -->|"retrieves chunks"| node_retriever
node_agnostic_pipeline -->|"generates answer"| node_generator
node_source_adapters -->|"reads database sources"| node_postgres
node_indexer -->|"creates FAISS index"| node_vector_indices
node_retriever -->|"searches index"| node_vector_indices
node_generator -->|"requests completion"| node_llm
node_generator -->|"returns answer"| node_answer
node_hybrid -->|"returns results"| node_answer
node_sessions -->|"stores session history"| node_app_db
node_storage -.->|"reads and writes"| node_object_storage

click node_api "https://github.com/krisnasetyadi/doculens-server/blob/main/main.py"
click node_auth "https://github.com/krisnasetyadi/doculens-server/blob/main/router/auth.py"
click node_pdf_upload "https://github.com/krisnasetyadi/doculens-server/blob/main/router/upload.py"
click node_pdf_collections "https://github.com/krisnasetyadi/doculens-server/blob/main/router/collections.py"
click node_pdf_processing "https://github.com/krisnasetyadi/doculens-server/blob/main/processor.py"
click node_chat_routes "https://github.com/krisnasetyadi/doculens-server/blob/main/router/chat.py"
click node_chat_parser "https://github.com/krisnasetyadi/doculens-server/blob/main/chat_parser.py"
click node_chat_ingest "https://github.com/krisnasetyadi/doculens-server/blob/main/chat_ingest.py"
click node_telegram "https://github.com/krisnasetyadi/doculens-server/blob/main/router/telegram.py"
click node_hybrid "https://github.com/krisnasetyadi/doculens-server/blob/main/router/hybrid.py"
click node_agnostic_pipeline "https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/pipeline.py"
click node_source_adapters "https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/adapters.py"
click node_indexer "https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/indexer.py"
click node_retriever "https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/retriever.py"
click node_generator "https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/generator.py"
click node_db_search "https://github.com/krisnasetyadi/doculens-server/blob/main/database.py"
click node_db_connections "https://github.com/krisnasetyadi/doculens-server/blob/main/router/database_connections.py"
click node_sessions "https://github.com/krisnasetyadi/doculens-server/blob/main/router/sessions.py"
click node_storage "https://github.com/krisnasetyadi/doculens-server/blob/main/storage.py"
click node_app_db "https://github.com/krisnasetyadi/doculens-server/blob/main/app_db.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_sessions,node_user toneBlue
class node_pdf_upload,node_pdf_collections,node_pdf_processing,node_chat_routes,node_chat_parser,node_chat_ingest,node_telegram,node_db_connections toneAmber
class node_hybrid,node_agnostic_pipeline,node_source_adapters,node_indexer,node_retriever,node_generator,node_db_search,node_answer toneMint
class node_storage,node_app_db,node_vector_indices toneRose
class node_postgres,node_object_storage,node_llm toneIndigo
```

## Components

### API and Accounts

- [FastAPI app](https://github.com/krisnasetyadi/doculens-server/blob/main/main.py): `main.py`
- [Authentication](https://github.com/krisnasetyadi/doculens-server/blob/main/router/auth.py): `router/auth.py`
- [Chat sessions](https://github.com/krisnasetyadi/doculens-server/blob/main/router/sessions.py): `router/sessions.py`

### Source Ingestion

- [PDF upload](https://github.com/krisnasetyadi/doculens-server/blob/main/router/upload.py): `router/upload.py`
- [PDF collections](https://github.com/krisnasetyadi/doculens-server/blob/main/router/collections.py): `router/collections.py`
- [PDF processing](https://github.com/krisnasetyadi/doculens-server/blob/main/processor.py): `processor.py`
- [Chat imports](https://github.com/krisnasetyadi/doculens-server/blob/main/router/chat.py): `router/chat.py`
- [Chat parsing](https://github.com/krisnasetyadi/doculens-server/blob/main/chat_parser.py): `chat_parser.py`
- [Chat indexing](https://github.com/krisnasetyadi/doculens-server/blob/main/chat_ingest.py): `chat_ingest.py`
- [Telegram sync](https://github.com/krisnasetyadi/doculens-server/blob/main/router/telegram.py): `router/telegram.py`
- [DB connections](https://github.com/krisnasetyadi/doculens-server/blob/main/router/database_connections.py): `router/database_connections.py`

### Retrieval and Answers

- [Hybrid query](https://github.com/krisnasetyadi/doculens-server/blob/main/router/hybrid.py): `router/hybrid.py`
- [Agnostic RAG](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/pipeline.py): `agnostic/pipeline.py`
- [Source adapters](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/adapters.py): `agnostic/adapters.py`
- [Runtime indexing](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/indexer.py): `agnostic/indexer.py`
- [Chunk retrieval](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/retriever.py): `agnostic/retriever.py`
- [Answer generation](https://github.com/krisnasetyadi/doculens-server/blob/main/agnostic/generator.py): `agnostic/generator.py`
- [Database search](https://github.com/krisnasetyadi/doculens-server/blob/main/database.py): `database.py`
- **Answer with sources**

### Persistence

- [Storage wrapper](https://github.com/krisnasetyadi/doculens-server/blob/main/storage.py): `storage.py`
- [App database](https://github.com/krisnasetyadi/doculens-server/blob/main/app_db.py): `app_db.py`
- **Vector indices**

### External Services

- **PostgreSQL**
- **Supabase storage**
- **LLM providers**

### Other components

- **User**

## Connections

- User → FastAPI app: sends requests
- FastAPI app → Authentication: dispatches auth
- FastAPI app → PDF upload: dispatches upload
- FastAPI app → PDF collections: dispatches collection requests
- FastAPI app → Hybrid query: dispatches queries
- FastAPI app → Chat imports: dispatches chat imports
- FastAPI app → Telegram sync: dispatches Telegram routes
- FastAPI app → Chat sessions: dispatches session requests
- FastAPI app → DB connections: dispatches connection requests
- PDF upload → PDF processing: processes PDFs
- PDF processing → Vector indices: builds index
- PDF collections → Storage wrapper: manages collection files
- Chat imports → Chat parsing: parses exports
- Chat imports → Chat indexing: ingests messages
- Telegram sync → Chat indexing: ingests synced messages
- Chat indexing → Vector indices: saves chat index
- Chat indexing → Storage wrapper: persists chat data
- Hybrid query → PDF processing: searches PDF collections
- Hybrid query → Database search: searches database
- Hybrid query → Chat indexing: searches chat collections
- Database search → PostgreSQL: queries
- DB connections → App database: stores connection records
- DB connections → PostgreSQL: inspects external schema
- Agnostic RAG → Source adapters: loads source data
- Agnostic RAG → Runtime indexing: builds index
- Agnostic RAG → Chunk retrieval: retrieves chunks
- Agnostic RAG → Answer generation: generates answer
- Source adapters → PostgreSQL: reads database sources
- Runtime indexing → Vector indices: creates FAISS index
- Chunk retrieval → Vector indices: searches index
- Answer generation → LLM providers: requests completion
- Answer generation → Answer with sources: returns answer
- Hybrid query → Answer with sources: returns results
- Chat sessions → App database: stores session history
- Storage wrapper → Supabase storage: reads and writes