# abhijith13923/ai-intellimail- architecture

> Architecture diagram of the GitHub repository abhijith13923/ai-intellimail-, 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/abhijith13923/ai-intellimail-
- Repository: https://github.com/abhijith13923/ai-intellimail-

## Overview

AI Gmail Intelligence Assistant lets a user authenticate with Google, sync Gmail messages into searchable indexes, and ask contextual questions that return grounded answers and source emails. The documented and sampled flow runs from the React chat through the FastAPI query endpoint and RAG orchestrator: parse intent, retrieve dense and keyword matches, rerank, then generate a response with trace data. A separate sync path feeds email into ingestion. The tree and excerpts establish these boundaries; some sync, generation, and storage wiring is inferred only at subsystem level from documentation and filenames.

Main entry points: [`backend/app/rag/pipeline.py`](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/pipeline.py) (RAG orchestrator), [`backend/app/main.py`](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/gmail/sync.py`](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/sync.py) (Email sync), [`backend/app/rag/ingestion.py`](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/ingestion.py) (Email ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["Login screen<br/>[App.jsx]"]
  node_chat["Chat dashboard<br/>[ChatDashboard.jsx]"]
  node_inspector["Trace inspector<br/>[ChunkInspector.jsx]"]
end

subgraph group_api["API and sync"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_oauth["Google OAuth<br/>[main.py]"]
  node_sync["Email sync<br/>[sync.py]"]
  node_gmail_auth["Gmail credentials<br/>[auth.py]"]
  node_gmail_service["Gmail fetch<br/>[service.py]"]
end

subgraph group_rag["RAG processing"]
  node_pipeline["RAG orchestrator<br/>[pipeline.py]"]
  node_ingestion["Email ingestion<br/>[ingestion.py]"]
  node_chunker["Email chunking<br/>[chunking.py]"]
  node_parser["Query parsing<br/>[query_parser.py]"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
  node_embeddings["Embedding service<br/>[embeddings.py]"]
end

subgraph group_stores["Indexes and state"]
  node_sync_state[("Sync progress<br/>[sync_state.py]")]
  node_vector[("Chroma vector index<br/>[vector_store.py]")]
  node_bm25[("BM25 index<br/>[bm25_store.py]")]
end

node_user(("Gmail user"))
node_google{{"Google services"}}
node_llm{{"Gemini / LLM"}}

node_user -->|"starts login"| node_app
node_app -->|"requests OAuth code"| node_google
node_app -->|"exchanges code"| node_api
node_api -->|"verifies credentials"| node_google
node_user -->|"asks or syncs"| node_chat
node_chat -->|"calls query and sync"| node_api
node_api -->|"runs query"| node_pipeline
node_pipeline -->|"parses intent"| node_parser
node_parser -->|"extracts filters"| node_llm
node_pipeline -->|"retrieves candidates"| node_retriever
node_retriever -->|"dense search"| node_vector
node_retriever -->|"keyword search"| node_bm25
node_vector -->|"embeds query"| node_embeddings
node_pipeline -->|"reranks candidates"| node_reranker
node_pipeline -->|"generates answer"| node_generator
node_generator -->|"produces response"| node_llm
node_pipeline -->|"returns answer and trace"| node_api
node_api -->|"returns results"| node_chat
node_chat -->|"shows retrieval trace"| node_inspector
node_api -->|"starts initial sync"| node_sync
node_sync -->|"gets credentials"| node_gmail_auth
node_gmail_auth -->|"refreshes token"| node_google
node_sync -->|"fetches messages"| node_gmail_service
node_gmail_service -->|"reads Gmail"| node_google
node_sync -->|"tracks progress"| node_sync_state
node_sync -->|"sends emails for indexing"| node_pipeline
node_pipeline -->|"ingests emails"| node_ingestion
node_api -->|"accepts manual ingest"| node_ingestion
node_ingestion -->|"cleans and chunks"| node_chunker
node_ingestion -->|"upserts chunks"| node_vector
node_ingestion -->|"adds documents"| node_bm25

click node_app "https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/App.jsx"
click node_chat "https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/components/ChatDashboard.jsx"
click node_inspector "https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/components/ChunkInspector.jsx"
click node_api "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/main.py"
click node_oauth "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/main.py"
click node_sync "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/sync.py"
click node_gmail_auth "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/auth.py"
click node_gmail_service "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/service.py"
click node_sync_state "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/sync_state.py"
click node_pipeline "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/pipeline.py"
click node_ingestion "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/ingestion.py"
click node_chunker "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/chunking.py"
click node_parser "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/query_parser.py"
click node_retriever "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/retriever.py"
click node_reranker "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/reranker.py"
click node_generator "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/generator.py"
click node_vector "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/vector_store.py"
click node_bm25 "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/bm25_store.py"
click node_embeddings "https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/embeddings.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_chat,node_inspector,node_user toneBlue
class node_api,node_oauth,node_sync,node_gmail_auth,node_gmail_service toneAmber
class node_pipeline,node_ingestion,node_chunker,node_parser,node_retriever,node_reranker,node_generator,node_embeddings toneMint
class node_sync_state,node_vector,node_bm25 toneRose
class node_google,node_llm toneIndigo
```

## Components

### User interface

- [Login screen](https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat dashboard](https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/components/ChatDashboard.jsx): `frontend/src/components/ChatDashboard.jsx`
- [Trace inspector](https://github.com/abhijith13923/ai-intellimail-/blob/main/frontend/src/components/ChunkInspector.jsx): `frontend/src/components/ChunkInspector.jsx`

### API and sync

- [FastAPI routes](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/main.py): `backend/app/main.py`
- [Google OAuth](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/main.py): `backend/app/main.py`
- [Email sync](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/sync.py): `backend/app/gmail/sync.py`
- [Gmail credentials](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/auth.py): `backend/app/gmail/auth.py`
- [Gmail fetch](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/gmail/service.py): `backend/app/gmail/service.py`

### RAG processing

- [RAG orchestrator](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/pipeline.py): `backend/app/rag/pipeline.py`
- [Email ingestion](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/ingestion.py): `backend/app/rag/ingestion.py`
- [Email chunking](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/chunking.py): `backend/app/rag/chunking.py`
- [Query parsing](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/query_parser.py): `backend/app/rag/query_parser.py`
- [Hybrid retrieval](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Result reranking](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/reranker.py): `backend/app/rag/reranker.py`
- [Answer generation](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/generator.py): `backend/app/rag/generator.py`
- [Embedding service](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`

### Indexes and state

- [Sync progress](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/sync_state.py): `backend/app/sync_state.py`
- [Chroma vector index](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/vector_store.py): `backend/app/rag/vector_store.py`
- [BM25 index](https://github.com/abhijith13923/ai-intellimail-/blob/main/backend/app/rag/bm25_store.py): `backend/app/rag/bm25_store.py`

### Other components

- **Gmail user**
- **Google services**
- **Gemini / LLM**

## Connections

- Gmail user → Login screen: starts login
- Login screen → Google services: requests OAuth code
- Login screen → FastAPI routes: exchanges code
- FastAPI routes → Google services: verifies credentials
- Gmail user → Chat dashboard: asks or syncs
- Chat dashboard → FastAPI routes: calls query and sync
- FastAPI routes → RAG orchestrator: runs query
- RAG orchestrator → Query parsing: parses intent
- Query parsing → Gemini / LLM: extracts filters
- RAG orchestrator → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → Chroma vector index: dense search
- Hybrid retrieval → BM25 index: keyword search
- Chroma vector index → Embedding service: embeds query
- RAG orchestrator → Result reranking: reranks candidates
- RAG orchestrator → Answer generation: generates answer
- Answer generation → Gemini / LLM: produces response
- RAG orchestrator → FastAPI routes: returns answer and trace
- FastAPI routes → Chat dashboard: returns results
- Chat dashboard → Trace inspector: shows retrieval trace
- FastAPI routes → Email sync: starts initial sync
- Email sync → Gmail credentials: gets credentials
- Gmail credentials → Google services: refreshes token
- Email sync → Gmail fetch: fetches messages
- Gmail fetch → Google services: reads Gmail
- Email sync → Sync progress: tracks progress
- Email sync → RAG orchestrator: sends emails for indexing
- RAG orchestrator → Email ingestion: ingests emails
- FastAPI routes → Email ingestion: accepts manual ingest
- Email ingestion → Email chunking: cleans and chunks
- Email ingestion → Chroma vector index: upserts chunks
- Email ingestion → BM25 index: adds documents