# andrea-ragalzi/document-intelligent-hub architecture

> Architecture diagram of the GitHub repository andrea-ragalzi/document-intelligent-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrea-ragalzi/document-intelligent-hub
- Repository: https://github.com/andrea-ragalzi/document-intelligent-hub

## Overview

Document Intelligent Hub lets people manage private PDF collections or explore a shared, read-only demo, then ask multilingual, document-grounded questions and inspect filename/page citations. The main flow runs from the Next.js client through FastAPI into document indexing or the RAG query workflow. Supporting capabilities include Firebase identity, guest-query limits, persisted registered-user conversations, and support submissions. The README documents the major flows; unsampled implementation details are represented at their existing directory paths rather than inferred as specific calls.

Main entry points: [`backend/app/routers/documents_router.py`](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/documents_router.py) (Document routes), [`frontend/app/dashboard/page.tsx`](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/app/dashboard/page.tsx) (Next.js experience), [`backend/app/services/rag_orchestrator_service.py`](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/rag_orchestrator_service.py) (RAG orchestration), [`backend/main.py`](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Next.js experience<br/>[page.tsx]"]
  node_chat["Chat and citations<br/>[useRAGChat.ts]"]
  node_conversation["Conversation persistence"]
  node_firebase_client["Firebase client<br/>[firebase.ts]"]
end

subgraph group_api["API and access"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth["Identity verification<br/>[auth.py]"]
  node_schemas["API contracts<br/>[rag_schema.py]"]
  node_guest_budget["Guest query budgets"]
  node_support["Support submissions<br/>[support_router.py]"]
end

subgraph group_documents["Document workflows"]
  node_documents_api["Document routes"]
  node_document_processing["PDF indexing"]
  node_document_management["Document management"]
  node_demo["Shared demo corpus"]
  node_file_storage["Original file storage"]
end

subgraph group_rag["Retrieval and answers"]
  node_query_api["Query routes<br/>[query_router.py]"]
  node_orchestrator["RAG orchestration"]
  node_query_parse["Query parsing"]
  node_query_process["Query reformulation"]
  node_vector_repository["Vector repository"]
end

subgraph group_integrations["Persistence and services"]
  node_chroma[("ChromaDB<br/>[chroma_client.py]")]
  node_openai{{"OpenAI"}}
  node_firebase{{"Firebase identity"}}
  node_firestore[("Firestore")]
  node_guest_usage["Guest usage adapter"]
  node_email["Email delivery"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"asks questions"| node_chat
node_chat -->|"sends REST query"| node_query_api
node_web -->|"manages PDFs"| node_documents_api
node_web -->|"calls REST API"| node_app
node_app -->|"registers routes"| node_documents_api
node_app -->|"registers routes"| node_query_api
node_app -->|"registers routes"| node_support
node_documents_api -->|"verifies identity"| node_auth
node_documents_api -->|"indexes PDFs"| node_document_processing
node_documents_api -->|"manages documents"| node_document_management
node_documents_api -->|"serves demo corpus"| node_demo
node_documents_api -->|"stores originals"| node_file_storage
node_document_processing -->|"indexes chunks"| node_chroma
node_query_api -->|"runs RAG"| node_orchestrator
node_query_api -->|"reserves guest budget"| node_guest_budget
node_guest_budget -->|"reserves usage"| node_guest_usage
node_guest_usage -.->|"persists usage"| node_firestore
node_orchestrator -.->|"parses filters"| node_query_parse
node_orchestrator -.->|"reformulates queries"| node_query_process
node_orchestrator -->|"retrieves evidence"| node_vector_repository
node_vector_repository -->|"reads and writes"| node_chroma
node_orchestrator -->|"generates answers"| node_openai
node_chat -->|"uses authentication"| node_firebase_client
node_firebase_client -->|"authenticates users"| node_firebase
node_conversation -->|"persists conversations"| node_firestore
node_web -->|"saves registered chats"| node_conversation
node_support -.->|"sends support mail"| node_email

click node_web "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/app/dashboard/page.tsx"
click node_chat "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/hooks/useRAGChat.ts"
click node_conversation "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/lib/conversationsService.ts"
click node_firebase_client "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/lib/firebase.ts"
click node_app "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/main.py"
click node_auth "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/core/auth.py"
click node_schemas "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/schemas/rag_schema.py"
click node_documents_api "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/documents_router.py"
click node_document_processing "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/document_indexing_service.py"
click node_document_management "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/document_management_service.py"
click node_demo "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/shared_demo_corpus_service.py"
click node_file_storage "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/local_file_storage.py"
click node_query_api "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/query_router.py"
click node_orchestrator "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/rag_orchestrator_service.py"
click node_query_parse "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/query_parser_service.py"
click node_query_process "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/query_processing_service.py"
click node_vector_repository "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/repositories/vector_store_repository.py"
click node_chroma "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/db/chroma_client.py"
click node_guest_budget "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/guest_query_budget_service.py"
click node_guest_usage "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/firestore_guest_usage.py"
click node_support "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/support_router.py"
click node_email "https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/resend_email_adapter.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_web,node_chat,node_conversation,node_firebase_client,node_user toneBlue
class node_app,node_auth,node_schemas,node_guest_budget,node_support toneAmber
class node_documents_api,node_document_processing,node_document_management,node_demo,node_file_storage toneMint
class node_query_api,node_orchestrator,node_query_parse,node_query_process,node_vector_repository toneRose
class node_chroma,node_openai,node_firebase,node_firestore,node_guest_usage,node_email toneIndigo
```

## Components

### Web client

- [Next.js experience](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Chat and citations](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/hooks/useRAGChat.ts): `frontend/hooks/useRAGChat.ts`
- [Conversation persistence](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/lib/conversationsService.ts): `frontend/lib/conversationsService.ts`
- [Firebase client](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/frontend/lib/firebase.ts): `frontend/lib/firebase.ts`

### API and access

- [FastAPI application](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/main.py): `backend/main.py`
- [Identity verification](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [API contracts](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/schemas/rag_schema.py): `backend/app/schemas/rag_schema.py`
- [Guest query budgets](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/guest_query_budget_service.py): `backend/app/services/guest_query_budget_service.py`
- [Support submissions](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/support_router.py): `backend/app/routers/support_router.py`

### Document workflows

- [Document routes](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/documents_router.py): `backend/app/routers/documents_router.py`
- [PDF indexing](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/document_indexing_service.py): `backend/app/services/document_indexing_service.py`
- [Document management](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/document_management_service.py): `backend/app/services/document_management_service.py`
- [Shared demo corpus](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/shared_demo_corpus_service.py): `backend/app/services/shared_demo_corpus_service.py`
- [Original file storage](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/local_file_storage.py): `backend/app/infrastructure/local_file_storage.py`

### Retrieval and answers

- [Query routes](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/routers/query_router.py): `backend/app/routers/query_router.py`
- [RAG orchestration](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/rag_orchestrator_service.py): `backend/app/services/rag_orchestrator_service.py`
- [Query parsing](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/query_parser_service.py): `backend/app/services/query_parser_service.py`
- [Query reformulation](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/services/query_processing_service.py): `backend/app/services/query_processing_service.py`
- [Vector repository](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/repositories/vector_store_repository.py): `backend/app/repositories/vector_store_repository.py`

### Persistence and services

- [ChromaDB](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/db/chroma_client.py): `backend/app/db/chroma_client.py`
- **OpenAI**
- **Firebase identity**
- **Firestore**
- [Guest usage adapter](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/firestore_guest_usage.py): `backend/app/infrastructure/firestore_guest_usage.py`
- [Email delivery](https://github.com/andrea-ragalzi/document-intelligent-hub/blob/main/backend/app/infrastructure/resend_email_adapter.py): `backend/app/infrastructure/resend_email_adapter.py`

### Other components

- **User**

## Connections

- User → Next.js experience: uses (evidence: `README.md`)
- Next.js experience → Chat and citations: asks questions (evidence: `README.md`)
- Chat and citations → Query routes: sends REST query (evidence: `README.md`)
- Next.js experience → Document routes: manages PDFs (evidence: `README.md`)
- Next.js experience → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Document routes: registers routes (evidence: `backend/main.py`)
- FastAPI application → Query routes: registers routes (evidence: `backend/main.py`)
- FastAPI application → Support submissions: registers routes (evidence: `backend/main.py`)
- Document routes → Identity verification: verifies identity (evidence: `backend/app/routers/documents_router.py`)
- Document routes → PDF indexing: indexes PDFs (evidence: `README.md`)
- Document routes → Document management: manages documents (evidence: `backend/app/routers/documents_router.py`)
- Document routes → Shared demo corpus: serves demo corpus (evidence: `backend/app/routers/documents_router.py`)
- Document routes → Original file storage: stores originals (evidence: `README.md`)
- PDF indexing → ChromaDB: indexes chunks (evidence: `README.md`)
- Query routes → RAG orchestration: runs RAG (evidence: `backend/app/routers/query_router.py`)
- Query routes → Guest query budgets: reserves guest budget (evidence: `backend/app/routers/query_router.py`)
- Guest query budgets → Guest usage adapter: reserves usage (evidence: `backend/app/services/guest_query_budget_service.py`)
- Guest usage adapter → Firestore: persists usage
- RAG orchestration → Query parsing: parses filters
- RAG orchestration → Query reformulation: reformulates queries
- RAG orchestration → Vector repository: retrieves evidence (evidence: `README.md`)
- Vector repository → ChromaDB: reads and writes (evidence: `backend/app/repositories/vector_store_repository.py`)
- RAG orchestration → OpenAI: generates answers (evidence: `README.md`)
- Chat and citations → Firebase client: uses authentication (evidence: `README.md`)
- Firebase client → Firebase identity: authenticates users (evidence: `README.md`)
- Conversation persistence → Firestore: persists conversations (evidence: `README.md`)
- Next.js experience → Conversation persistence: saves registered chats (evidence: `README.md`)
- Support submissions → Email delivery: sends support mail
