# kos0-col/minirag architecture

> Architecture diagram of the GitHub repository kos0-col/minirag, 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/kos0-col/minirag
- Repository: https://github.com/kos0-col/minirag

## Overview

Mini RAG Pro is a web app for authenticated, document-grounded chat. Users sign in, create chats, upload documents, ask questions, and receive Gemini-generated answers grounded in retrieved chunks; they can also manage agents and explore the app’s other pages. The README documents document extraction, chunking, query caching, and agent management. The sampled sources confirm frontend state and local chat storage, server setup, auth logic, and parts of retrieval; several route and document-processing implementations were not sampled, so their internal wiring is shown only where documented.

Main entry points: [`server.js`](https://github.com/kos0-col/minirag/blob/main/server.js) (Express server), [`frontend/src/App.tsx`](https://github.com/kos0-col/minirag/blob/main/frontend/src/App.tsx) (App routing), [`queryService.js`](https://github.com/kos0-col/minirag/blob/main/queryService.js) (RAG query service), [`frontend/src/services/apiClient.ts`](https://github.com/kos0-col/minirag/blob/main/frontend/src/services/apiClient.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_app["App routing<br/>[App.tsx]"]
  node_chatpage["Chat page<br/>[ChatPage.tsx]"]
  node_docsui["Documents page<br/>[DocumentsPage.tsx]"]
  node_explore["Explore page<br/>[ExplorePage.tsx]"]
  node_authui["Login and registration<br/>[LoginPage.tsx]"]
  node_client["API client<br/>[apiClient.ts]"]
end

subgraph group_api["API and services"]
  node_server["Express server<br/>[server.js]"]
  node_authroutes["Auth routes<br/>[auth.js]"]
  node_chatroutes["Chat routes<br/>[chats.js]"]
  node_docroutes["Document routes<br/>[documents.js]"]
  node_queryroutes["Query routes<br/>[queries.js]"]
  node_agentroutes["Agent routes<br/>[agents.js]"]
  node_authservice["Authentication service<br/>[authService.js]"]
  node_chatservice["Chat service<br/>[chatService.js]"]
end

subgraph group_rag["RAG workflow"]
  node_docservice["Document processing<br/>[documentService.js]"]
  node_queryservice["RAG query service<br/>[queryService.js]"]
end

subgraph group_state["Application state"]
  node_store["App store<br/>[useAppStore.ts]"]
  node_chatstorage["Local chat storage<br/>[chatStorage.ts]"]
  node_chunkengine["Local document chunking<br/>[chunkEngine.ts]"]
  node_repo["Agent and skill catalog<br/>[repoService.ts]"]
end

subgraph group_data["Persistent data"]
  node_db[("Application database")]
  node_entities["Domain entities<br/>[DocumentChunk.js]"]
  node_cache[("Query cache<br/>[CacheEntry.js]")]
end

node_user(("User"))
node_gemini{{"Gemini API"}}
node_google{{"Google OAuth"}}

node_user -->|"uses"| node_app
node_app -->|"routes"| node_authui
node_app -->|"routes"| node_chatpage
node_app -->|"routes"| node_docsui
node_app -->|"routes"| node_explore
node_chatpage -->|"reads and updates"| node_store
node_chatpage -->|"requests"| node_client
node_docsui -->|"requests"| node_client
node_authui -->|"authenticates"| node_client
node_client -->|"HTTP API"| node_server
node_store -->|"persists chats"| node_chatstorage
node_docsui -->|"processes files"| node_chunkengine
node_explore -->|"browses catalog"| node_repo
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_chatroutes
node_server -->|"mounts"| node_docroutes
node_server -->|"mounts"| node_queryroutes
node_server -->|"mounts"| node_agentroutes
node_authroutes -->|"delegates auth"| node_authservice
node_authservice -.->|"verifies OAuth"| node_google
node_authservice -->|"reads and writes users"| node_db
node_chatroutes -->|"delegates chat operations"| node_chatservice
node_chatservice -->|"reads and writes chats"| node_db
node_docroutes -->|"processes uploads"| node_docservice
node_docservice -->|"stores documents and chunks"| node_db
node_queryroutes -->|"submits questions"| node_queryservice
node_queryservice -->|"retrieves chunks"| node_db
node_queryservice -->|"embeds and generates"| node_gemini
node_agentroutes -->|"manages agents"| node_db
node_entities -->|"defines schema"| node_db
node_queryservice -.->|"caches queries"| node_cache

click node_app "https://github.com/kos0-col/minirag/blob/main/frontend/src/App.tsx"
click node_chatpage "https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/ChatPage.tsx"
click node_docsui "https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/DocumentsPage.tsx"
click node_explore "https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/ExplorePage.tsx"
click node_authui "https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/LoginPage.tsx"
click node_client "https://github.com/kos0-col/minirag/blob/main/frontend/src/services/apiClient.ts"
click node_store "https://github.com/kos0-col/minirag/blob/main/frontend/src/store/useAppStore.ts"
click node_chatstorage "https://github.com/kos0-col/minirag/blob/main/frontend/src/utils/chatStorage.ts"
click node_chunkengine "https://github.com/kos0-col/minirag/blob/main/frontend/src/utils/chunkEngine.ts"
click node_repo "https://github.com/kos0-col/minirag/blob/main/frontend/src/services/repoService.ts"
click node_server "https://github.com/kos0-col/minirag/blob/main/server.js"
click node_authroutes "https://github.com/kos0-col/minirag/blob/main/src/routes/auth.js"
click node_chatroutes "https://github.com/kos0-col/minirag/blob/main/src/routes/chats.js"
click node_docroutes "https://github.com/kos0-col/minirag/blob/main/src/routes/documents.js"
click node_queryroutes "https://github.com/kos0-col/minirag/blob/main/src/routes/queries.js"
click node_agentroutes "https://github.com/kos0-col/minirag/blob/main/src/routes/agents.js"
click node_authservice "https://github.com/kos0-col/minirag/blob/main/src/services/authService.js"
click node_chatservice "https://github.com/kos0-col/minirag/blob/main/src/services/chatService.js"
click node_docservice "https://github.com/kos0-col/minirag/blob/main/documentService.js"
click node_queryservice "https://github.com/kos0-col/minirag/blob/main/queryService.js"
click node_entities "https://github.com/kos0-col/minirag/blob/main/src/entities/DocumentChunk.js"
click node_cache "https://github.com/kos0-col/minirag/blob/main/src/entities/CacheEntry.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_app,node_chatpage,node_docsui,node_explore,node_authui,node_client,node_user toneBlue
class node_server,node_authroutes,node_chatroutes,node_docroutes,node_queryroutes,node_agentroutes,node_authservice,node_chatservice toneAmber
class node_docservice,node_queryservice,node_gemini toneMint
class node_store,node_chatstorage,node_chunkengine,node_repo toneRose
class node_db,node_entities,node_cache,node_google toneIndigo
```

## Components

### Web app

- [App routing](https://github.com/kos0-col/minirag/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat page](https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Documents page](https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/DocumentsPage.tsx): `frontend/src/pages/DocumentsPage.tsx`
- [Explore page](https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/ExplorePage.tsx): `frontend/src/pages/ExplorePage.tsx`
- [Login and registration](https://github.com/kos0-col/minirag/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [API client](https://github.com/kos0-col/minirag/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### API and services

- [Express server](https://github.com/kos0-col/minirag/blob/main/server.js): `server.js`
- [Auth routes](https://github.com/kos0-col/minirag/blob/main/src/routes/auth.js): `src/routes/auth.js`
- [Chat routes](https://github.com/kos0-col/minirag/blob/main/src/routes/chats.js): `src/routes/chats.js`
- [Document routes](https://github.com/kos0-col/minirag/blob/main/src/routes/documents.js): `src/routes/documents.js`
- [Query routes](https://github.com/kos0-col/minirag/blob/main/src/routes/queries.js): `src/routes/queries.js`
- [Agent routes](https://github.com/kos0-col/minirag/blob/main/src/routes/agents.js): `src/routes/agents.js`
- [Authentication service](https://github.com/kos0-col/minirag/blob/main/src/services/authService.js): `src/services/authService.js`
- [Chat service](https://github.com/kos0-col/minirag/blob/main/src/services/chatService.js): `src/services/chatService.js`

### RAG workflow

- [Document processing](https://github.com/kos0-col/minirag/blob/main/documentService.js): `documentService.js`
- [RAG query service](https://github.com/kos0-col/minirag/blob/main/queryService.js): `queryService.js`

### Application state

- [App store](https://github.com/kos0-col/minirag/blob/main/frontend/src/store/useAppStore.ts): `frontend/src/store/useAppStore.ts`
- [Local chat storage](https://github.com/kos0-col/minirag/blob/main/frontend/src/utils/chatStorage.ts): `frontend/src/utils/chatStorage.ts`
- [Local document chunking](https://github.com/kos0-col/minirag/blob/main/frontend/src/utils/chunkEngine.ts): `frontend/src/utils/chunkEngine.ts`
- [Agent and skill catalog](https://github.com/kos0-col/minirag/blob/main/frontend/src/services/repoService.ts): `frontend/src/services/repoService.ts`

### Persistent data

- **Application database**
- [Domain entities](https://github.com/kos0-col/minirag/blob/main/src/entities/DocumentChunk.js): `src/entities/DocumentChunk.js`
- [Query cache](https://github.com/kos0-col/minirag/blob/main/src/entities/CacheEntry.js): `src/entities/CacheEntry.js`

### Other components

- **User**
- **Gemini API**
- **Google OAuth**

## Connections

- User → App routing: uses
- App routing → Login and registration: routes
- App routing → Chat page: routes
- App routing → Documents page: routes
- App routing → Explore page: routes
- Chat page → App store: reads and updates
- Chat page → API client: requests
- Documents page → API client: requests
- Login and registration → API client: authenticates
- API client → Express server: HTTP API
- App store → Local chat storage: persists chats
- Documents page → Local document chunking: processes files
- Explore page → Agent and skill catalog: browses catalog
- Express server → Auth routes: mounts
- Express server → Chat routes: mounts
- Express server → Document routes: mounts
- Express server → Query routes: mounts
- Express server → Agent routes: mounts
- Auth routes → Authentication service: delegates auth
- Authentication service → Google OAuth: verifies OAuth
- Authentication service → Application database: reads and writes users
- Chat routes → Chat service: delegates chat operations
- Chat service → Application database: reads and writes chats
- Document routes → Document processing: processes uploads
- Document processing → Application database: stores documents and chunks
- Query routes → RAG query service: submits questions
- RAG query service → Application database: retrieves chunks
- RAG query service → Gemini API: embeds and generates
- Agent routes → Application database: manages agents
- Domain entities → Application database: defines schema
- RAG query service → Query cache: caches queries