# mahad816/drivemind_ai architecture

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

- Interactive diagram: https://gitdiagram.com/mahad816/drivemind_ai
- Repository: https://github.com/mahad816/drivemind_ai

## Overview

DriveMind is a single-user Google Drive knowledge assistant. A user authorizes read-only Drive access, prepares a local index through sync, ingest, chunk, and build stages, then asks questions in chat and follows citations to indexed text. The graph preserves the documented specialized query routes, optional LangGraph and hybrid retrieval, file inspection, and browser-local chat history. Preparation and RAG service excerpts are partial; stage wiring beyond documented behavior is shown at subsystem level, not as unverified internal calls.

Main entry points: [`backend/app/api/router.py`](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/api/router.py) (FastAPI routes), [`backend/app/services/rag_service.py`](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/rag_service.py) (RAG orchestration), [`frontend/lib/api/client.ts`](https://github.com/mahad816/drivemind_ai/blob/main/frontend/lib/api/client.ts) (Browser API client), [`frontend/components/chat/chat-interface.tsx`](https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/chat/chat-interface.tsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_chat_ui["Chat interface<br/>[chat-interface.tsx]"]
  node_prep_ui["Prepare knowledge"]
  node_files_ui["File library"]
  node_source_ui["Source viewer<br/>[source-viewer.tsx]"]
  node_conversation_store["Chat history<br/>[storage.ts]"]
end

subgraph group_api["API and access"]
  node_api_client["Browser API client<br/>[client.ts]"]
  node_api_router["FastAPI routes<br/>[router.py]"]
  node_oauth["Drive OAuth"]
  node_source_api["Citation source API<br/>[sources.py]"]
end

subgraph group_prep["Knowledge preparation"]
  node_sync["Metadata sync"]
  node_drive_client["Drive connector<br/>[client.py]"]
  node_ingest["Content ingestion"]
  node_extract["Text extraction<br/>[registry.py]"]
  node_chunk["Chunking"]
  node_index_build["Index building"]
  node_embed["Embedding service<br/>[openai_service.py]"]
end

subgraph group_answer["Question answering"]
  node_rag["RAG orchestration<br/>[rag_service.py]"]
  node_router["Query routing<br/>[query_router.py]"]
  node_retrieval["Retrieval<br/>[hybrid.py]"]
  node_inventory["File inventory<br/>[file_inventory.py]"]
  node_file_target["Named-file search<br/>[file_target.py]"]
  node_agent_graph["Optional agent graph<br/>[graph.py]"]
end

subgraph group_state["Persistent state"]
  node_pg[("PostgreSQL")]
  node_vectors[("Qdrant vectors")]
end

node_user(("DriveMind user"))
node_drive_api["Google Drive API"]
node_openai["OpenAI services"]

node_user -->|"asks"| node_chat_ui
node_user -->|"prepares"| node_prep_ui
node_chat_ui -->|"submits questions"| node_api_client
node_prep_ui -->|"starts jobs"| node_api_client
node_files_ui -->|"requests files"| node_api_client
node_source_ui -->|"requests chunks"| node_api_client
node_api_client -->|"HTTP requests"| node_api_router
node_chat_ui -->|"stores history"| node_conversation_store
node_api_router -->|"starts authorization"| node_oauth
node_oauth -->|"authorizes access"| node_drive_api
node_api_router -->|"starts sync"| node_sync
node_sync -->|"lists changes"| node_drive_client
node_drive_client -->|"reads metadata"| node_drive_api
node_api_router -->|"starts ingest"| node_ingest
node_ingest -->|"fetches content"| node_drive_client
node_ingest -->|"extracts text"| node_extract
node_api_router -->|"starts chunking"| node_chunk
node_api_router -->|"starts build"| node_index_build
node_index_build -->|"embeds chunks"| node_embed
node_embed -->|"requests embeddings"| node_openai
node_index_build -->|"writes vectors"| node_vectors
node_api_router -->|"dispatches chat"| node_rag
node_rag -->|"classifies question"| node_router
node_rag -->|"retrieves evidence"| node_retrieval
node_rag -->|"searches inventory"| node_inventory
node_rag -->|"searches named file"| node_file_target
node_rag -.->|"optionally dispatches"| node_agent_graph
node_retrieval -->|"searches vectors"| node_vectors
node_retrieval -->|"searches text and metadata"| node_pg
node_rag -->|"generates answers"| node_openai
node_rag -->|"persists answers"| node_pg
node_api_router -->|"routes citation lookup"| node_source_api
node_source_api -->|"reads indexed chunks"| node_pg

click node_chat_ui "https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/chat/chat-interface.tsx"
click node_prep_ui "https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/knowledge/prepare-knowledge-view.tsx"
click node_files_ui "https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/files/knowledge-library.tsx"
click node_source_ui "https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/sources/source-viewer.tsx"
click node_conversation_store "https://github.com/mahad816/drivemind_ai/blob/main/frontend/lib/conversations/storage.ts"
click node_api_client "https://github.com/mahad816/drivemind_ai/blob/main/frontend/lib/api/client.ts"
click node_api_router "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/api/router.py"
click node_oauth "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/google_oauth_service.py"
click node_sync "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/drive_sync_service.py"
click node_drive_client "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/connectors/google_drive/client.py"
click node_ingest "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/ingestion_service.py"
click node_extract "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/ingestion/extractors/registry.py"
click node_chunk "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/chunking_service.py"
click node_index_build "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/indexing_service.py"
click node_embed "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/embeddings/openai_service.py"
click node_rag "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/rag_service.py"
click node_router "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/query_router.py"
click node_retrieval "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/hybrid.py"
click node_inventory "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/file_inventory.py"
click node_file_target "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/file_target.py"
click node_agent_graph "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/agents/drive_graph/graph.py"
click node_source_api "https://github.com/mahad816/drivemind_ai/blob/main/backend/app/api/sources.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_chat_ui,node_prep_ui,node_files_ui,node_source_ui,node_conversation_store,node_user toneBlue
class node_api_client,node_api_router,node_oauth,node_source_api toneAmber
class node_sync,node_drive_client,node_ingest,node_extract,node_chunk,node_index_build,node_embed,node_drive_api toneMint
class node_rag,node_router,node_retrieval,node_inventory,node_file_target,node_agent_graph toneRose
class node_pg,node_vectors,node_openai toneIndigo
```

## Components

### Browser experience

- [Chat interface](https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/chat/chat-interface.tsx): `frontend/components/chat/chat-interface.tsx`
- [Prepare knowledge](https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/knowledge/prepare-knowledge-view.tsx): `frontend/components/knowledge/prepare-knowledge-view.tsx`
- [File library](https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/files/knowledge-library.tsx): `frontend/components/files/knowledge-library.tsx`
- [Source viewer](https://github.com/mahad816/drivemind_ai/blob/main/frontend/components/sources/source-viewer.tsx): `frontend/components/sources/source-viewer.tsx`
- [Chat history](https://github.com/mahad816/drivemind_ai/blob/main/frontend/lib/conversations/storage.ts): `frontend/lib/conversations/storage.ts`

### API and access

- [Browser API client](https://github.com/mahad816/drivemind_ai/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`
- [FastAPI routes](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Drive OAuth](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/google_oauth_service.py): `backend/app/services/google_oauth_service.py`
- [Citation source API](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/api/sources.py): `backend/app/api/sources.py`

### Knowledge preparation

- [Metadata sync](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/drive_sync_service.py): `backend/app/services/drive_sync_service.py`
- [Drive connector](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/connectors/google_drive/client.py): `backend/app/connectors/google_drive/client.py`
- [Content ingestion](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Text extraction](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/ingestion/extractors/registry.py): `backend/app/ingestion/extractors/registry.py`
- [Chunking](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/chunking_service.py): `backend/app/services/chunking_service.py`
- [Index building](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/indexing_service.py): `backend/app/services/indexing_service.py`
- [Embedding service](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/embeddings/openai_service.py): `backend/app/embeddings/openai_service.py`

### Question answering

- [RAG orchestration](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Query routing](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/query_router.py): `backend/app/retrieval/query_router.py`
- [Retrieval](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [File inventory](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/file_inventory.py): `backend/app/retrieval/file_inventory.py`
- [Named-file search](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/retrieval/file_target.py): `backend/app/retrieval/file_target.py`
- [Optional agent graph](https://github.com/mahad816/drivemind_ai/blob/main/backend/app/agents/drive_graph/graph.py): `backend/app/agents/drive_graph/graph.py`

### Persistent state

- **PostgreSQL**
- **Qdrant vectors**

### Other components

- **DriveMind user**
- **Google Drive API**
- **OpenAI services**

## Connections

- DriveMind user → Chat interface: asks
- DriveMind user → Prepare knowledge: prepares
- Chat interface → Browser API client: submits questions
- Prepare knowledge → Browser API client: starts jobs
- File library → Browser API client: requests files
- Source viewer → Browser API client: requests chunks
- Browser API client → FastAPI routes: HTTP requests
- Chat interface → Chat history: stores history
- FastAPI routes → Drive OAuth: starts authorization
- Drive OAuth → Google Drive API: authorizes access
- FastAPI routes → Metadata sync: starts sync
- Metadata sync → Drive connector: lists changes
- Drive connector → Google Drive API: reads metadata
- FastAPI routes → Content ingestion: starts ingest
- Content ingestion → Drive connector: fetches content
- Content ingestion → Text extraction: extracts text
- FastAPI routes → Chunking: starts chunking
- FastAPI routes → Index building: starts build
- Index building → Embedding service: embeds chunks
- Embedding service → OpenAI services: requests embeddings
- Index building → Qdrant vectors: writes vectors
- FastAPI routes → RAG orchestration: dispatches chat
- RAG orchestration → Query routing: classifies question
- RAG orchestration → Retrieval: retrieves evidence
- RAG orchestration → File inventory: searches inventory
- RAG orchestration → Named-file search: searches named file
- RAG orchestration → Optional agent graph: optionally dispatches
- Retrieval → Qdrant vectors: searches vectors
- Retrieval → PostgreSQL: searches text and metadata
- RAG orchestration → OpenAI services: generates answers
- RAG orchestration → PostgreSQL: persists answers
- FastAPI routes → Citation source API: routes citation lookup
- Citation source API → PostgreSQL: reads indexed chunks