# kishankumar1328/kirstonai architecture

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

## Overview

KirstonAI combines conversational AI, document-grounded retrieval, autonomous coding, and multimodal utilities in a React/FastAPI application. The typical path is user → routed UI page → API endpoint → service/orchestrator → model or retrieval, with conversation state persisted in PostgreSQL. Separate branches provide coding tools, search, speech synthesis, analytics, and 3D generation. The README documents orchestration and integrations; sampled source confirms app/router registration and selected tool, ingestion, and UI behavior, but not every service-to-service call, so uncertain wiring is omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/App.tsx) (Page router), [`frontend/src/services/api.ts`](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/main.py`](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api`](https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/api) (Feature endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Page router<br/>[App.tsx]"]
  node_chatui["Chat UI<br/>[ChatPage.tsx]"]
  node_codingui["Coding UI"]
  node_fileui["File chat UI<br/>[FileChatPage.tsx]"]
  node_otherui["Product pages"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API boundary"]
  node_server["FastAPI app<br/>[main.py]"]
  node_chatapi["Chat endpoint<br/>[chat.py]"]
  node_codingapi["Coding endpoint<br/>[coding_agent.py]"]
  node_featureapi["Feature endpoints"]
end

subgraph group_ai["AI and retrieval"]
  node_agentgraph["Query orchestrator<br/>[graph.py]"]
  node_agentnodes["Agent pathways<br/>[nodes.py]"]
  node_llm["LLM provider<br/>[llm.py]"]
  node_rag["RAG pipeline"]
  node_ingestion["Document chunking<br/>[ingestion.py]"]
end

subgraph group_domain["Product services"]
  node_chatservice["Chat service<br/>[chat_service.py]"]
  node_coding["Coding engine"]
  node_codingtools["Coding tools<br/>[tools_engine.py]"]
  node_workspace["Workspace operations"]
  node_terminal["Terminal execution"]
  node_speech["Speech synthesis<br/>[tts_service.py]"]
  node_object3d["3D generation"]
  node_conversation["Conversation service"]
end

subgraph group_state["Persistence"]
  node_repos["Repositories"]
  node_db[("PostgreSQL<br/>[session.py]")]
  node_vectors[("Vector store<br/>[vectorstore.py]")]
end

node_user(("User"))
node_modelservice{{"AI model APIs"}}
node_speechproviders{{"TTS providers"}}
node_generationapi{{"3D generation API"}}

node_user -->|"opens"| node_app
node_app -->|"routes"| node_chatui
node_app -->|"routes"| node_codingui
node_app -->|"routes"| node_fileui
node_app -->|"routes"| node_otherui
node_chatui -->|"requests"| node_client
node_codingui -->|"requests"| node_client
node_fileui -->|"requests"| node_client
node_otherui -->|"requests"| node_client
node_client -->|"HTTP requests"| node_server
node_server -->|"mounts"| node_chatapi
node_server -->|"mounts"| node_codingapi
node_server -->|"mounts"| node_featureapi
node_chatapi -->|"dispatches"| node_chatservice
node_chatservice -->|"invokes"| node_agentgraph
node_agentgraph -->|"routes"| node_agentnodes
node_agentnodes -->|"requests inference"| node_llm
node_agentnodes -->|"retrieves context"| node_rag
node_llm -->|"calls"| node_modelservice
node_rag -->|"searches"| node_vectors
node_ingestion -->|"stores chunks"| node_vectors
node_codingapi -->|"dispatches"| node_coding
node_coding -->|"executes tools"| node_codingtools
node_codingtools -->|"operates files"| node_workspace
node_codingtools -->|"runs commands"| node_terminal
node_featureapi -->|"dispatches TTS"| node_speech
node_speech -.->|"synthesizes with"| node_speechproviders
node_featureapi -->|"dispatches generation"| node_object3d
node_object3d -.->|"calls"| node_generationapi
node_conversation -->|"uses"| node_repos
node_repos -->|"reads and writes"| node_db
node_chatservice -->|"manages threads"| node_conversation

click node_app "https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/App.tsx"
click node_chatui "https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/ChatPage.tsx"
click node_codingui "https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/CodingAgentPage.tsx"
click node_fileui "https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/FileChatPage.tsx"
click node_otherui "https://github.com/kishankumar1328/kirstonai/tree/main/frontend/src/pages"
click node_client "https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/services/api.ts"
click node_server "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/main.py"
click node_chatapi "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/api/chat.py"
click node_codingapi "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/api/coding_agent.py"
click node_featureapi "https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/api"
click node_chatservice "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/chat_service.py"
click node_agentgraph "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/agents/graph.py"
click node_agentnodes "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/agents/nodes.py"
click node_llm "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/ai/llm.py"
click node_rag "https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/rag"
click node_ingestion "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/rag/ingestion.py"
click node_coding "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/coding_agent_service.py"
click node_codingtools "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/tools_engine.py"
click node_workspace "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/workspace_manager.py"
click node_terminal "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/terminal_executor.py"
click node_speech "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/tts_service.py"
click node_object3d "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/object3d_service.py"
click node_conversation "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/conversation_service.py"
click node_repos "https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/repositories"
click node_db "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/database/session.py"
click node_vectors "https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/rag/vectorstore.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_chatui,node_codingui,node_fileui,node_otherui,node_client,node_user toneBlue
class node_server,node_chatapi,node_codingapi,node_featureapi toneAmber
class node_agentgraph,node_agentnodes,node_llm,node_rag,node_ingestion,node_modelservice,node_generationapi toneMint
class node_chatservice,node_coding,node_codingtools,node_workspace,node_terminal,node_speech,node_object3d,node_conversation toneRose
class node_repos,node_db,node_vectors,node_speechproviders toneIndigo
```

## Components

### User interface

- [Page router](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat UI](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Coding UI](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/CodingAgentPage.tsx): `frontend/src/pages/CodingAgentPage.tsx`
- [File chat UI](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/pages/FileChatPage.tsx): `frontend/src/pages/FileChatPage.tsx`
- [Product pages](https://github.com/kishankumar1328/kirstonai/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/kishankumar1328/kirstonai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API boundary

- [FastAPI app](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoint](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Coding endpoint](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/api/coding_agent.py): `backend/app/api/coding_agent.py`
- [Feature endpoints](https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/api): `backend/app/api`

### AI and retrieval

- [Query orchestrator](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Agent pathways](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/agents/nodes.py): `backend/app/agents/nodes.py`
- [LLM provider](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/ai/llm.py): `backend/app/ai/llm.py`
- [RAG pipeline](https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/rag): `backend/app/rag`
- [Document chunking](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/rag/ingestion.py): `backend/app/rag/ingestion.py`

### Product services

- [Chat service](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/chat_service.py): `backend/app/services/chat_service.py`
- [Coding engine](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/coding_agent_service.py): `backend/app/services/coding_agent_service.py`
- [Coding tools](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/tools_engine.py): `backend/app/services/tools_engine.py`
- [Workspace operations](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/workspace_manager.py): `backend/app/services/workspace_manager.py`
- [Terminal execution](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/terminal_executor.py): `backend/app/services/terminal_executor.py`
- [Speech synthesis](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/tts_service.py): `backend/app/services/tts_service.py`
- [3D generation](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/object3d_service.py): `backend/app/services/object3d_service.py`
- [Conversation service](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/services/conversation_service.py): `backend/app/services/conversation_service.py`

### Persistence

- [Repositories](https://github.com/kishankumar1328/kirstonai/tree/main/backend/app/repositories): `backend/app/repositories`
- [PostgreSQL](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/database/session.py): `backend/app/database/session.py`
- [Vector store](https://github.com/kishankumar1328/kirstonai/blob/main/backend/app/rag/vectorstore.py): `backend/app/rag/vectorstore.py`

### Other components

- **User**
- **AI model APIs**
- **TTS providers**
- **3D generation API**

## Connections

- User → Page router: opens
- Page router → Chat UI: routes
- Page router → Coding UI: routes
- Page router → File chat UI: routes
- Page router → Product pages: routes
- Chat UI → API client: requests
- Coding UI → API client: requests
- File chat UI → API client: requests
- Product pages → API client: requests
- API client → FastAPI app: HTTP requests
- FastAPI app → Chat endpoint: mounts
- FastAPI app → Coding endpoint: mounts
- FastAPI app → Feature endpoints: mounts
- Chat endpoint → Chat service: dispatches
- Chat service → Query orchestrator: invokes
- Query orchestrator → Agent pathways: routes
- Agent pathways → LLM provider: requests inference
- Agent pathways → RAG pipeline: retrieves context
- LLM provider → AI model APIs: calls
- RAG pipeline → Vector store: searches
- Document chunking → Vector store: stores chunks
- Coding endpoint → Coding engine: dispatches
- Coding engine → Coding tools: executes tools
- Coding tools → Workspace operations: operates files
- Coding tools → Terminal execution: runs commands
- Feature endpoints → Speech synthesis: dispatches TTS
- Speech synthesis → TTS providers: synthesizes with
- Feature endpoints → 3D generation: dispatches generation
- 3D generation → 3D generation API: calls
- Conversation service → Repositories: uses
- Repositories → PostgreSQL: reads and writes
- Chat service → Conversation service: manages threads