# mugnihidayah/synapse-instant-document-insight architecture

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

- Interactive diagram: https://gitdiagram.com/mugnihidayah/synapse-instant-document-insight
- Repository: https://github.com/mugnihidayah/synapse-instant-document-insight

## Overview

Synapse is a FastAPI multimodal document-Q&A service. Its main workflow is API-key-authenticated session creation and upload, optional background ingestion, extraction and chunk storage, then grounded answers with citations; users can also inspect sessions, export history, submit feedback, and review usage. The graph preserves README-documented capabilities such as OCR, hybrid retrieval, agentic tools, and query filters. Some subsystem wiring is documented rather than shown in the sampled source, so uncertain call relationships are omitted.

Main entry points: [`src/api/routes/query.py`](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/query.py) (Query routes), [`src/api/main.py`](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/main.py) (FastAPI application), [`src/api/routes/documents.py`](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/documents.py) (Document routes), [`src/rag/hybrid_search.py`](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/hybrid_search.py) (Hybrid search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_app["FastAPI application<br/>[main.py]"]
  node_keys["API key routes<br/>[keys.py]"]
  node_documents["Document routes<br/>[documents.py]"]
  node_queryroute["Query routes<br/>[query.py]"]
  node_insights["Insights routes<br/>[insights.py]"]
  node_session["Session service<br/>[session.py]"]
  node_auth["API key auth<br/>[auth.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_jobs["Async ingestion jobs<br/>[ingestion_jobs.py]"]
  node_contract["Ingestion contract"]
  node_loaders["File loaders<br/>[loaders.py]"]
  node_chunkers["Document chunking<br/>[chunkers.py]"]
  node_filters["Metadata filters"]
  node_file_storage["Original file storage<br/>[file_storage.py]"]
end

subgraph group_query["RAG and agents"]
  node_queryflow["Query orchestration<br/>[query.py]"]
  node_contextualize["History contextualization<br/>[contextualize.py]"]
  node_rewrite["Query rewriting<br/>[query_rewrite.py]"]
  node_hybrid["Hybrid search<br/>[hybrid_search.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_tuning["Retrieval tuning<br/>[retrieval_utils.py]"]
  node_grounding["Grounding checks<br/>[grounding.py]"]
  node_chain["Answer generation<br/>[chain.py]"]
  node_agent["Agent orchestration<br/>[orchestrator.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_history["Chat history<br/>[chat_history.py]"]
end

subgraph group_state["Persistence and usage"]
  node_pgvector["Vector storage<br/>[pgvector_store.py]"]
  node_db[("PostgreSQL and pgvector<br/>[connection.py]")]
  node_models["Database models<br/>[models.py]"]
  node_usage["Usage and quota<br/>[usage.py]"]
end

node_client(("API client"))
node_llm(("LLM and embedding providers"))

node_client -->|"sends requests"| node_app
node_app -->|"dispatches"| node_documents
node_app -->|"dispatches"| node_queryroute
node_app -->|"dispatches"| node_keys
node_app -->|"dispatches"| node_insights
node_documents -->|"authenticates"| node_auth
node_queryroute -->|"authenticates"| node_auth
node_insights -->|"authenticates"| node_auth
node_documents -->|"manages sessions"| node_session
node_documents -->|"persists uploads"| node_file_storage
node_documents -->|"schedules ingestion"| node_jobs
node_jobs -->|"updates status"| node_session
node_jobs -->|"processes payloads"| node_contract
node_contract -->|"extracts content"| node_loaders
node_contract -->|"creates chunks"| node_chunkers
node_contract -->|"stores chunks"| node_pgvector
node_loaders -.->|"uses OCR"| node_llm
node_pgvector -->|"reads and writes"| node_db
node_keys -->|"stores key records"| node_db
node_session -->|"reads and writes"| node_db
node_queryroute -->|"loads session"| node_session
node_queryroute -->|"loads chat history"| node_history
node_queryroute -->|"contextualizes query"| node_contextualize
node_queryroute -->|"retrieves documents"| node_hybrid
node_hybrid -->|"vector search"| node_pgvector
node_hybrid -->|"keyword search"| node_db
node_hybrid -->|"applies filters"| node_filters
node_queryroute -->|"reranks results"| node_reranker
node_queryroute -->|"generates answer"| node_chain
node_queryroute -->|"checks grounding"| node_grounding
node_queryroute -->|"runs agent mode"| node_agent
node_agent -->|"executes tools"| node_tools
node_agent -->|"retrieves sources"| node_hybrid
node_chain -->|"requests completion"| node_llm
node_insights -->|"reports usage"| node_usage
node_usage -->|"reads and writes"| node_db

click node_app "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/main.py"
click node_keys "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/keys.py"
click node_documents "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/documents.py"
click node_queryroute "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/query.py"
click node_insights "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/insights.py"
click node_session "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/session.py"
click node_auth "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/auth.py"
click node_jobs "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/ingestion_jobs.py"
click node_contract "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/ingestion_contract.py"
click node_loaders "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/loaders.py"
click node_chunkers "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/chunkers.py"
click node_filters "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/metadata_filters.py"
click node_file_storage "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/file_storage.py"
click node_queryflow "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/query.py"
click node_contextualize "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/contextualize.py"
click node_rewrite "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/query_rewrite.py"
click node_hybrid "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/hybrid_search.py"
click node_reranker "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/reranker.py"
click node_tuning "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/retrieval_utils.py"
click node_grounding "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/grounding.py"
click node_chain "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/chain.py"
click node_agent "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/agent/orchestrator.py"
click node_tools "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/agent/tools.py"
click node_history "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/chat_history.py"
click node_pgvector "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/pgvector_store.py"
click node_db "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/db/connection.py"
click node_models "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/db/models.py"
click node_usage "https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/usage.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_app,node_keys,node_documents,node_queryroute,node_insights,node_session,node_auth,node_client toneBlue
class node_jobs,node_contract,node_loaders,node_chunkers,node_filters,node_file_storage toneAmber
class node_queryflow,node_contextualize,node_rewrite,node_hybrid,node_reranker,node_tuning,node_grounding,node_chain,node_agent,node_tools,node_history toneMint
class node_pgvector,node_db,node_models,node_usage toneRose
class node_llm toneIndigo
```

## Components

### API and sessions

- [FastAPI application](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/main.py): `src/api/main.py`
- [API key routes](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/keys.py): `src/api/routes/keys.py`
- [Document routes](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/documents.py): `src/api/routes/documents.py`
- [Query routes](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/query.py): `src/api/routes/query.py`
- [Insights routes](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/insights.py): `src/api/routes/insights.py`
- [Session service](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/session.py): `src/api/session.py`
- [API key auth](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/auth.py): `src/api/auth.py`

### Document ingestion

- [Async ingestion jobs](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/ingestion_jobs.py): `src/api/ingestion_jobs.py`
- [Ingestion contract](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/ingestion_contract.py): `src/api/ingestion_contract.py`
- [File loaders](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/loaders.py): `src/ingestion/loaders.py`
- [Document chunking](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/chunkers.py): `src/ingestion/chunkers.py`
- [Metadata filters](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/metadata_filters.py): `src/ingestion/metadata_filters.py`
- [Original file storage](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/file_storage.py): `src/ingestion/file_storage.py`

### RAG and agents

- [Query orchestration](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/routes/query.py): `src/api/routes/query.py`
- [History contextualization](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/contextualize.py): `src/rag/contextualize.py`
- [Query rewriting](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/query_rewrite.py): `src/rag/query_rewrite.py`
- [Hybrid search](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/hybrid_search.py): `src/rag/hybrid_search.py`
- [Result reranking](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/reranker.py): `src/rag/reranker.py`
- [Retrieval tuning](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/retrieval_utils.py): `src/rag/retrieval_utils.py`
- [Grounding checks](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/grounding.py): `src/rag/grounding.py`
- [Answer generation](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/chain.py): `src/rag/chain.py`
- [Agent orchestration](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/agent/orchestrator.py): `src/agent/orchestrator.py`
- [Agent tools](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/agent/tools.py): `src/agent/tools.py`
- [Chat history](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/rag/chat_history.py): `src/rag/chat_history.py`

### Persistence and usage

- [Vector storage](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/ingestion/pgvector_store.py): `src/ingestion/pgvector_store.py`
- [PostgreSQL and pgvector](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/db/connection.py): `src/db/connection.py`
- [Database models](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/db/models.py): `src/db/models.py`
- [Usage and quota](https://github.com/mugnihidayah/synapse-instant-document-insight/blob/main/src/api/usage.py): `src/api/usage.py`

### Other components

- **API client**
- **LLM and embedding providers**

## Connections

- API client → FastAPI application: sends requests
- FastAPI application → Document routes: dispatches
- FastAPI application → Query routes: dispatches
- FastAPI application → API key routes: dispatches
- FastAPI application → Insights routes: dispatches
- Document routes → API key auth: authenticates
- Query routes → API key auth: authenticates
- Insights routes → API key auth: authenticates
- Document routes → Session service: manages sessions
- Document routes → Original file storage: persists uploads
- Document routes → Async ingestion jobs: schedules ingestion
- Async ingestion jobs → Session service: updates status
- Async ingestion jobs → Ingestion contract: processes payloads
- Ingestion contract → File loaders: extracts content
- Ingestion contract → Document chunking: creates chunks
- Ingestion contract → Vector storage: stores chunks
- File loaders → LLM and embedding providers: uses OCR
- Vector storage → PostgreSQL and pgvector: reads and writes
- API key routes → PostgreSQL and pgvector: stores key records
- Session service → PostgreSQL and pgvector: reads and writes
- Query routes → Session service: loads session
- Query routes → Chat history: loads chat history
- Query routes → History contextualization: contextualizes query
- Query routes → Hybrid search: retrieves documents
- Hybrid search → Vector storage: vector search
- Hybrid search → PostgreSQL and pgvector: keyword search
- Hybrid search → Metadata filters: applies filters
- Query routes → Result reranking: reranks results
- Query routes → Answer generation: generates answer
- Query routes → Grounding checks: checks grounding
- Query routes → Agent orchestration: runs agent mode
- Agent orchestration → Agent tools: executes tools
- Agent orchestration → Hybrid search: retrieves sources
- Answer generation → LLM and embedding providers: requests completion
- Insights routes → Usage and quota: reports usage
- Usage and quota → PostgreSQL and pgvector: reads and writes