# achintxv/citemind architecture

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

- Interactive diagram: https://gitdiagram.com/achintxv/citemind
- Repository: https://github.com/achintxv/citemind

## Overview

CiteMind is a document-grounded chat application. Users upload PDFs or text files, which are validated, extracted, chunked, embedded, and stored for semantic retrieval. In chat, the server loads conversation history, checks the question, retrieves relevant chunks, generates a grounded answer, validates its output, and persists the result with citations. The UI also supports browsing and deleting documents and conversations. The sampled sources show the core ingestion and RAG calls; some API routing and model-provider details are supported only by the source index, so uncertain integrations are omitted or marked dashed.

Main entry points: [`src/services/document.service.js`](https://github.com/achintxv/citemind/blob/master/src/services/document.service.js) (Document ingestion), [`src/services/rag.service.js`](https://github.com/achintxv/citemind/blob/master/src/services/rag.service.js) (RAG answer flow), [`src/lib/api-client.js`](https://github.com/achintxv/citemind/blob/master/src/lib/api-client.js) (Browser API client), [`src/components/ChatInterface.jsx`](https://github.com/achintxv/citemind/blob/master/src/components/ChatInterface.jsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_chat_ui["Chat interface<br/>[ChatInterface.jsx]"]
  node_message_ui["Message views<br/>[MessageList.jsx]"]
  node_message_input["Message input<br/>[MessageInput.jsx]"]
  node_sidebar["Chat sidebar<br/>[Sidebar.jsx]"]
  node_documents_page["Documents page<br/>[page.jsx]"]
  node_document_list["Document list<br/>[DocumentList.jsx]"]
  node_uploader["Document uploader"]
  node_citation["Source citations<br/>[SourceCitation.jsx]"]
end

subgraph group_api["API routes"]
  node_chat_route["Chat endpoint<br/>[route.js]"]
  node_conversations_route["Conversation endpoints<br/>[route.js]"]
  node_conversation_id_route["Conversation detail<br/>[route.js]"]
  node_documents_route["Document endpoints<br/>[route.js]"]
  node_document_id_route["Document detail<br/>[route.js]"]
  node_upload_route["Upload endpoint<br/>[route.js]"]
end

subgraph group_domain["Document and chat services"]
  node_rag["RAG answer flow<br/>[rag.service.js]"]
  node_conversation_service["Conversation service"]
  node_document_service["Document ingestion"]
  node_extraction["Text extraction<br/>[extract.js]"]
  node_chunking["Text chunking<br/>[chunk.js]"]
  node_embedding["Embedding service"]
  node_retrieval["Vector retrieval"]
  node_gemini["Gemini model service<br/>[gemini.service.js]"]
end

subgraph group_safety["Guardrails and shared infrastructure"]
  node_api_client["Browser API client<br/>[api-client.js]"]
  node_input_guard["Input validation<br/>[input.guard.js]"]
  node_injection_guard["Injection detection<br/>[injection.guard.js]"]
  node_retrieval_guard["Retrieval checks<br/>[retrieval.guard.js]"]
  node_output_guard["Output validation<br/>[output.guard.js]"]
  node_prompt["Prompt construction<br/>[prompt.js]"]
  node_env["Runtime configuration<br/>[env.js]"]
  node_response["Response handling<br/>[response.js]"]
end

node_user(("User"))
node_pg[("PostgreSQL and pgvector")]
node_local_files[("Uploaded file storage")]
node_external_model(("External model provider<br/>external system"))

node_user -->|"asks questions"| node_chat_ui
node_user -->|"manages documents"| node_documents_page
node_chat_ui -->|"renders"| node_message_input
node_chat_ui -->|"renders"| node_message_ui
node_chat_ui -->|"renders"| node_sidebar
node_message_ui -->|"renders"| node_citation
node_documents_page -->|"renders"| node_document_list
node_documents_page -->|"renders"| node_uploader
node_chat_ui -->|"calls"| node_api_client
node_documents_page -->|"calls"| node_api_client
node_uploader -->|"calls"| node_api_client
node_api_client -->|"posts chat"| node_chat_route
node_api_client -->|"requests conversations"| node_conversations_route
node_api_client -->|"requests conversation"| node_conversation_id_route
node_api_client -->|"requests documents"| node_documents_route
node_api_client -->|"uploads files"| node_upload_route
node_chat_route -->|"answers via"| node_rag
node_conversations_route -->|"delegates to"| node_conversation_service
node_conversation_id_route -->|"delegates to"| node_conversation_service
node_documents_route -->|"delegates to"| node_document_service
node_document_id_route -->|"delegates to"| node_document_service
node_upload_route -->|"ingests through"| node_document_service
node_chat_route -->|"validates input"| node_input_guard
node_upload_route -->|"checks upload"| node_input_guard
node_rag -->|"persists turns"| node_conversation_service
node_rag -->|"searches chunks"| node_retrieval
node_rag -->|"checks question"| node_injection_guard
node_rag -->|"checks context"| node_retrieval_guard
node_rag -->|"builds prompt"| node_prompt
node_rag -->|"generates answer"| node_gemini
node_rag -->|"validates answer"| node_output_guard
node_document_service -->|"validates file"| node_input_guard
node_document_service -->|"extracts text"| node_extraction
node_document_service -->|"chunks text"| node_chunking
node_document_service -->|"embeds chunks"| node_embedding
node_document_service -->|"stores chunks"| node_retrieval
node_document_service -->|"writes metadata"| node_pg
node_document_service -->|"stores original"| node_local_files
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"filters results"| node_retrieval_guard
node_retrieval -->|"queries vectors"| node_pg
node_embedding -->|"requests embeddings"| node_gemini
node_prompt -->|"flags text"| node_injection_guard
node_gemini -->|"reads settings"| node_env
node_chat_route -->|"formats response"| node_response
node_gemini -.->|"calls provider"| node_external_model

click node_chat_ui "https://github.com/achintxv/citemind/blob/master/src/components/ChatInterface.jsx"
click node_message_ui "https://github.com/achintxv/citemind/blob/master/src/components/MessageList.jsx"
click node_message_input "https://github.com/achintxv/citemind/blob/master/src/components/MessageInput.jsx"
click node_sidebar "https://github.com/achintxv/citemind/blob/master/src/components/Sidebar.jsx"
click node_documents_page "https://github.com/achintxv/citemind/blob/master/src/app/documents/page.jsx"
click node_document_list "https://github.com/achintxv/citemind/blob/master/src/components/DocumentList.jsx"
click node_uploader "https://github.com/achintxv/citemind/blob/master/src/components/DocumentUploader.jsx"
click node_citation "https://github.com/achintxv/citemind/blob/master/src/components/SourceCitation.jsx"
click node_api_client "https://github.com/achintxv/citemind/blob/master/src/lib/api-client.js"
click node_chat_route "https://github.com/achintxv/citemind/blob/master/src/app/api/chat/route.js"
click node_conversations_route "https://github.com/achintxv/citemind/blob/master/src/app/api/chat/conversations/route.js"
click node_conversation_id_route "https://github.com/achintxv/citemind/blob/master/src/app/api/chat/conversations/%5Bid%5D/route.js"
click node_documents_route "https://github.com/achintxv/citemind/blob/master/src/app/api/documents/route.js"
click node_document_id_route "https://github.com/achintxv/citemind/blob/master/src/app/api/documents/%5Bid%5D/route.js"
click node_upload_route "https://github.com/achintxv/citemind/blob/master/src/app/api/documents/upload/route.js"
click node_rag "https://github.com/achintxv/citemind/blob/master/src/services/rag.service.js"
click node_conversation_service "https://github.com/achintxv/citemind/blob/master/src/services/conversation.service.js"
click node_document_service "https://github.com/achintxv/citemind/blob/master/src/services/document.service.js"
click node_extraction "https://github.com/achintxv/citemind/blob/master/src/ingestion/extract.js"
click node_chunking "https://github.com/achintxv/citemind/blob/master/src/ingestion/chunk.js"
click node_embedding "https://github.com/achintxv/citemind/blob/master/src/services/embedding.service.js"
click node_retrieval "https://github.com/achintxv/citemind/blob/master/src/services/retrieval.service.js"
click node_gemini "https://github.com/achintxv/citemind/blob/master/src/services/gemini.service.js"
click node_input_guard "https://github.com/achintxv/citemind/blob/master/src/guardrails/input.guard.js"
click node_injection_guard "https://github.com/achintxv/citemind/blob/master/src/guardrails/injection.guard.js"
click node_retrieval_guard "https://github.com/achintxv/citemind/blob/master/src/guardrails/retrieval.guard.js"
click node_output_guard "https://github.com/achintxv/citemind/blob/master/src/guardrails/output.guard.js"
click node_prompt "https://github.com/achintxv/citemind/blob/master/src/utils/prompt.js"
click node_env "https://github.com/achintxv/citemind/blob/master/src/lib/env.js"
click node_response "https://github.com/achintxv/citemind/blob/master/src/utils/response.js"

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_message_ui,node_message_input,node_sidebar,node_documents_page,node_document_list,node_uploader,node_citation,node_user toneBlue
class node_chat_route,node_conversations_route,node_conversation_id_route,node_documents_route,node_document_id_route,node_upload_route,node_pg,node_local_files toneAmber
class node_rag,node_conversation_service,node_document_service,node_extraction,node_chunking,node_embedding,node_retrieval,node_gemini toneMint
class node_api_client,node_input_guard,node_injection_guard,node_retrieval_guard,node_output_guard,node_prompt,node_env,node_response toneRose
class node_external_model toneIndigo
```

## Components

### User interface

- [Chat interface](https://github.com/achintxv/citemind/blob/master/src/components/ChatInterface.jsx): `src/components/ChatInterface.jsx`
- [Message views](https://github.com/achintxv/citemind/blob/master/src/components/MessageList.jsx): `src/components/MessageList.jsx`
- [Message input](https://github.com/achintxv/citemind/blob/master/src/components/MessageInput.jsx): `src/components/MessageInput.jsx`
- [Chat sidebar](https://github.com/achintxv/citemind/blob/master/src/components/Sidebar.jsx): `src/components/Sidebar.jsx`
- [Documents page](https://github.com/achintxv/citemind/blob/master/src/app/documents/page.jsx): `src/app/documents/page.jsx`
- [Document list](https://github.com/achintxv/citemind/blob/master/src/components/DocumentList.jsx): `src/components/DocumentList.jsx`
- [Document uploader](https://github.com/achintxv/citemind/blob/master/src/components/DocumentUploader.jsx): `src/components/DocumentUploader.jsx`
- [Source citations](https://github.com/achintxv/citemind/blob/master/src/components/SourceCitation.jsx): `src/components/SourceCitation.jsx`

### API routes

- [Chat endpoint](https://github.com/achintxv/citemind/blob/master/src/app/api/chat/route.js): `src/app/api/chat/route.js`
- [Conversation endpoints](https://github.com/achintxv/citemind/blob/master/src/app/api/chat/conversations/route.js): `src/app/api/chat/conversations/route.js`
- [Conversation detail](https://github.com/achintxv/citemind/blob/master/src/app/api/chat/conversations/%5Bid%5D/route.js): `src/app/api/chat/conversations/[id]/route.js`
- [Document endpoints](https://github.com/achintxv/citemind/blob/master/src/app/api/documents/route.js): `src/app/api/documents/route.js`
- [Document detail](https://github.com/achintxv/citemind/blob/master/src/app/api/documents/%5Bid%5D/route.js): `src/app/api/documents/[id]/route.js`
- [Upload endpoint](https://github.com/achintxv/citemind/blob/master/src/app/api/documents/upload/route.js): `src/app/api/documents/upload/route.js`

### Document and chat services

- [RAG answer flow](https://github.com/achintxv/citemind/blob/master/src/services/rag.service.js): `src/services/rag.service.js`
- [Conversation service](https://github.com/achintxv/citemind/blob/master/src/services/conversation.service.js): `src/services/conversation.service.js`
- [Document ingestion](https://github.com/achintxv/citemind/blob/master/src/services/document.service.js): `src/services/document.service.js`
- [Text extraction](https://github.com/achintxv/citemind/blob/master/src/ingestion/extract.js): `src/ingestion/extract.js`
- [Text chunking](https://github.com/achintxv/citemind/blob/master/src/ingestion/chunk.js): `src/ingestion/chunk.js`
- [Embedding service](https://github.com/achintxv/citemind/blob/master/src/services/embedding.service.js): `src/services/embedding.service.js`
- [Vector retrieval](https://github.com/achintxv/citemind/blob/master/src/services/retrieval.service.js): `src/services/retrieval.service.js`
- [Gemini model service](https://github.com/achintxv/citemind/blob/master/src/services/gemini.service.js): `src/services/gemini.service.js`

### Guardrails and shared infrastructure

- [Browser API client](https://github.com/achintxv/citemind/blob/master/src/lib/api-client.js): `src/lib/api-client.js`
- [Input validation](https://github.com/achintxv/citemind/blob/master/src/guardrails/input.guard.js): `src/guardrails/input.guard.js`
- [Injection detection](https://github.com/achintxv/citemind/blob/master/src/guardrails/injection.guard.js): `src/guardrails/injection.guard.js`
- [Retrieval checks](https://github.com/achintxv/citemind/blob/master/src/guardrails/retrieval.guard.js): `src/guardrails/retrieval.guard.js`
- [Output validation](https://github.com/achintxv/citemind/blob/master/src/guardrails/output.guard.js): `src/guardrails/output.guard.js`
- [Prompt construction](https://github.com/achintxv/citemind/blob/master/src/utils/prompt.js): `src/utils/prompt.js`
- [Runtime configuration](https://github.com/achintxv/citemind/blob/master/src/lib/env.js): `src/lib/env.js`
- [Response handling](https://github.com/achintxv/citemind/blob/master/src/utils/response.js): `src/utils/response.js`

### Other components

- **User**
- **PostgreSQL and pgvector**
- **Uploaded file storage**
- **External model provider**: external system

## Connections

- User → Chat interface: asks questions
- User → Documents page: manages documents
- Chat interface → Message input: renders (evidence: `src/components/ChatInterface.jsx`)
- Chat interface → Message views: renders (evidence: `src/components/ChatInterface.jsx`)
- Chat interface → Chat sidebar: renders (evidence: `src/components/ChatInterface.jsx`)
- Message views → Source citations: renders (evidence: `src/components/MessageList.jsx`)
- Documents page → Document list: renders (evidence: `src/app/documents/page.jsx`)
- Documents page → Document uploader: renders (evidence: `src/app/documents/page.jsx`)
- Chat interface → Browser API client: calls (evidence: `src/components/ChatInterface.jsx`)
- Documents page → Browser API client: calls (evidence: `src/app/documents/page.jsx`)
- Document uploader → Browser API client: calls (evidence: `src/components/DocumentUploader.jsx`)
- Browser API client → Chat endpoint: posts chat
- Browser API client → Conversation endpoints: requests conversations
- Browser API client → Conversation detail: requests conversation
- Browser API client → Document endpoints: requests documents
- Browser API client → Upload endpoint: uploads files
- Chat endpoint → RAG answer flow: answers via (evidence: `src/app/api/chat/route.js`)
- Conversation endpoints → Conversation service: delegates to (evidence: `src/app/api/chat/conversations/route.js`)
- Conversation detail → Conversation service: delegates to (evidence: `src/app/api/chat/conversations/[id]/route.js`)
- Document endpoints → Document ingestion: delegates to (evidence: `src/app/api/documents/route.js`)
- Document detail → Document ingestion: delegates to (evidence: `src/app/api/documents/[id]/route.js`)
- Upload endpoint → Document ingestion: ingests through (evidence: `src/app/api/documents/upload/route.js`)
- Chat endpoint → Input validation: validates input (evidence: `src/app/api/chat/route.js`)
- Upload endpoint → Input validation: checks upload (evidence: `src/app/api/documents/upload/route.js`)
- RAG answer flow → Conversation service: persists turns (evidence: `src/services/rag.service.js`)
- RAG answer flow → Vector retrieval: searches chunks (evidence: `src/services/rag.service.js`)
- RAG answer flow → Injection detection: checks question (evidence: `src/services/rag.service.js`)
- RAG answer flow → Retrieval checks: checks context (evidence: `src/services/rag.service.js`)
- RAG answer flow → Prompt construction: builds prompt (evidence: `src/services/rag.service.js`)
- RAG answer flow → Gemini model service: generates answer (evidence: `src/services/rag.service.js`)
- RAG answer flow → Output validation: validates answer (evidence: `src/services/rag.service.js`)
- Document ingestion → Input validation: validates file (evidence: `src/services/document.service.js`)
- Document ingestion → Text extraction: extracts text (evidence: `src/services/document.service.js`)
- Document ingestion → Text chunking: chunks text (evidence: `src/services/document.service.js`)
- Document ingestion → Embedding service: embeds chunks (evidence: `src/services/document.service.js`)
- Document ingestion → Vector retrieval: stores chunks (evidence: `src/services/document.service.js`)
- Document ingestion → PostgreSQL and pgvector: writes metadata (evidence: `src/services/document.service.js`)
- Document ingestion → Uploaded file storage: stores original (evidence: `src/services/document.service.js`)
- Vector retrieval → Embedding service: embeds query (evidence: `src/services/retrieval.service.js`)
- Vector retrieval → Retrieval checks: filters results (evidence: `src/services/retrieval.service.js`)
- Vector retrieval → PostgreSQL and pgvector: queries vectors (evidence: `src/services/retrieval.service.js`)
- Embedding service → Gemini model service: requests embeddings (evidence: `src/services/embedding.service.js`)
- Prompt construction → Injection detection: flags text (evidence: `src/utils/prompt.js`)
- Gemini model service → Runtime configuration: reads settings (evidence: `src/services/gemini.service.js`)
- Chat endpoint → Response handling: formats response (evidence: `src/app/api/chat/route.js`)
- Gemini model service → External model provider: calls provider
