# ajay8x/ai architecture

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

- Interactive diagram: https://gitdiagram.com/ajay8x/ai
- Repository: https://github.com/ajay8x/ai

## Overview

AJAX AI is a local-first assistant offering web and voice interaction, multilingual intent routing, local language-model responses, guarded tools, memory, and document-grounded RAG. The main workflow is a user query entering the web chat or voice session, reaching the central router, then being classified and answered through tools and/or the local model; conversation data is persisted. Document uploads form a separate indexing-and-retrieval branch. The graph preserves documented system, plugin, and neural capabilities; links to unsampled subsystems are omitted unless supported by the README or source index.

Main entry points: [`core/router.py`](https://github.com/ajay8x/ai/blob/main/core/router.py) (Query router), [`database/crud.py`](https://github.com/ajay8x/ai/blob/main/database/crud.py) (Persistence operations), [`api/server.py`](https://github.com/ajay8x/ai/blob/main/api/server.py) (FastAPI server), [`ai/rag/store.py`](https://github.com/ajay8x/ai/blob/main/ai/rag/store.py) (Document retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web dashboard<br/>[app.js]"]
  node_api["FastAPI server<br/>[server.py]"]
  node_chat["Chat controller<br/>[chat_controller.py]"]
  node_voice["Voice session<br/>[manager.py]"]
end

subgraph group_routing["Assistant orchestration"]
  node_router["Query router<br/>[router.py]"]
  node_intent["Intent classifier"]
  node_llm["Local model brain<br/>[factory.py]"]
  node_context["Prompt context<br/>[context.py]"]
end

subgraph group_knowledge["Knowledge and memory"]
  node_upload["Document upload"]
  node_rag[("Document retrieval<br/>[store.py]")]
  node_graph_rag["Graph RAG<br/>[graph_rag.py]"]
  node_knowledge_graph[("Knowledge graph<br/>[knowledge_graph.py]")]
  node_memory["User memory<br/>[manager.py]"]
end

subgraph group_actions["Tools and extensions"]
  node_tools["Tool registry<br/>[registry.py]"]
  node_rag_tools["RAG tools<br/>[rag_tools.py]"]
  node_graph_tools["Graph RAG tools<br/>[graphrag_tools.py]"]
  node_plugins["Plugin manager<br/>[manager.py]"]
end

subgraph group_operations["Platform services"]
  node_database[("Application database<br/>[db.py]")]
  node_crud["Persistence operations<br/>[crud.py]"]
  node_auth["Authentication<br/>[auth_controller.py]"]
  node_system["System diagnostics"]
  node_monitor["Hardware monitor<br/>[monitor.py]"]
  node_config["Runtime configuration<br/>[config_loader.py]"]
end

node_user(("Assistant user"))

node_user -->|"uses"| node_web
node_web -.->|"requests"| node_api
node_api -->|"routes to"| node_chat
node_chat -->|"processes query"| node_router
node_user -->|"speaks to"| node_voice
node_voice -->|"routes query"| node_router
node_router -->|"classifies with"| node_intent
node_router -->|"generates with"| node_llm
node_router -->|"dispatches tools"| node_tools
node_router -->|"builds context"| node_context
node_chat -->|"persists chat"| node_crud
node_upload -->|"indexes documents"| node_rag
node_rag -->|"uses database"| node_database
node_context -->|"retrieves documents"| node_rag
node_context -->|"loads history"| node_crud
node_memory -->|"reads and writes"| node_crud
node_rag_tools -->|"queries documents"| node_rag
node_graph_tools -->|"invokes retrieval"| node_graph_rag
node_graph_tools -->|"uses graph"| node_knowledge_graph
node_graph_rag -->|"queries graph"| node_knowledge_graph
node_graph_rag -->|"uses model"| node_llm
node_plugins -->|"registers tools"| node_tools
node_crud -->|"accesses storage"| node_database
node_auth -->|"persists sessions"| node_crud
node_api -->|"routes to"| node_auth
node_api -->|"routes to"| node_system
node_system -->|"reads telemetry"| node_monitor
node_system -->|"tests classifier"| node_intent
node_config -->|"configures storage"| node_database

click node_web "https://github.com/ajay8x/ai/blob/main/frontend/js/app.js"
click node_api "https://github.com/ajay8x/ai/blob/main/api/server.py"
click node_chat "https://github.com/ajay8x/ai/blob/main/controllers/chat_controller.py"
click node_voice "https://github.com/ajay8x/ai/blob/main/voice/manager.py"
click node_router "https://github.com/ajay8x/ai/blob/main/core/router.py"
click node_intent "https://github.com/ajay8x/ai/blob/main/ai/neural/intent_classifier.py"
click node_llm "https://github.com/ajay8x/ai/blob/main/ai/llm/factory.py"
click node_context "https://github.com/ajay8x/ai/blob/main/core/context.py"
click node_upload "https://github.com/ajay8x/ai/blob/main/controllers/upload_controller.py"
click node_rag "https://github.com/ajay8x/ai/blob/main/ai/rag/store.py"
click node_graph_rag "https://github.com/ajay8x/ai/blob/main/ai/rag/graph_rag.py"
click node_knowledge_graph "https://github.com/ajay8x/ai/blob/main/ai/rag/knowledge_graph.py"
click node_memory "https://github.com/ajay8x/ai/blob/main/memory/manager.py"
click node_tools "https://github.com/ajay8x/ai/blob/main/tools/registry.py"
click node_rag_tools "https://github.com/ajay8x/ai/blob/main/tools/rag_tools.py"
click node_graph_tools "https://github.com/ajay8x/ai/blob/main/tools/graphrag_tools.py"
click node_plugins "https://github.com/ajay8x/ai/blob/main/plugins/manager.py"
click node_database "https://github.com/ajay8x/ai/blob/main/database/db.py"
click node_crud "https://github.com/ajay8x/ai/blob/main/database/crud.py"
click node_auth "https://github.com/ajay8x/ai/blob/main/controllers/auth_controller.py"
click node_system "https://github.com/ajay8x/ai/blob/main/controllers/system_controller.py"
click node_monitor "https://github.com/ajay8x/ai/blob/main/system/monitor.py"
click node_config "https://github.com/ajay8x/ai/blob/main/config/config_loader.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_web,node_api,node_chat,node_voice,node_user toneBlue
class node_router,node_intent,node_llm,node_context toneAmber
class node_upload,node_rag,node_graph_rag,node_knowledge_graph,node_memory toneMint
class node_tools,node_rag_tools,node_graph_tools,node_plugins toneRose
class node_database,node_crud,node_auth,node_system,node_monitor,node_config toneIndigo
```

## Components

### User interfaces

- [Web dashboard](https://github.com/ajay8x/ai/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [FastAPI server](https://github.com/ajay8x/ai/blob/main/api/server.py): `api/server.py`
- [Chat controller](https://github.com/ajay8x/ai/blob/main/controllers/chat_controller.py): `controllers/chat_controller.py`
- [Voice session](https://github.com/ajay8x/ai/blob/main/voice/manager.py): `voice/manager.py`

### Assistant orchestration

- [Query router](https://github.com/ajay8x/ai/blob/main/core/router.py): `core/router.py`
- [Intent classifier](https://github.com/ajay8x/ai/blob/main/ai/neural/intent_classifier.py): `ai/neural/intent_classifier.py`
- [Local model brain](https://github.com/ajay8x/ai/blob/main/ai/llm/factory.py): `ai/llm/factory.py`
- [Prompt context](https://github.com/ajay8x/ai/blob/main/core/context.py): `core/context.py`

### Knowledge and memory

- [Document upload](https://github.com/ajay8x/ai/blob/main/controllers/upload_controller.py): `controllers/upload_controller.py`
- [Document retrieval](https://github.com/ajay8x/ai/blob/main/ai/rag/store.py): `ai/rag/store.py`
- [Graph RAG](https://github.com/ajay8x/ai/blob/main/ai/rag/graph_rag.py): `ai/rag/graph_rag.py`
- [Knowledge graph](https://github.com/ajay8x/ai/blob/main/ai/rag/knowledge_graph.py): `ai/rag/knowledge_graph.py`
- [User memory](https://github.com/ajay8x/ai/blob/main/memory/manager.py): `memory/manager.py`

### Tools and extensions

- [Tool registry](https://github.com/ajay8x/ai/blob/main/tools/registry.py): `tools/registry.py`
- [RAG tools](https://github.com/ajay8x/ai/blob/main/tools/rag_tools.py): `tools/rag_tools.py`
- [Graph RAG tools](https://github.com/ajay8x/ai/blob/main/tools/graphrag_tools.py): `tools/graphrag_tools.py`
- [Plugin manager](https://github.com/ajay8x/ai/blob/main/plugins/manager.py): `plugins/manager.py`

### Platform services

- [Application database](https://github.com/ajay8x/ai/blob/main/database/db.py): `database/db.py`
- [Persistence operations](https://github.com/ajay8x/ai/blob/main/database/crud.py): `database/crud.py`
- [Authentication](https://github.com/ajay8x/ai/blob/main/controllers/auth_controller.py): `controllers/auth_controller.py`
- [System diagnostics](https://github.com/ajay8x/ai/blob/main/controllers/system_controller.py): `controllers/system_controller.py`
- [Hardware monitor](https://github.com/ajay8x/ai/blob/main/system/monitor.py): `system/monitor.py`
- [Runtime configuration](https://github.com/ajay8x/ai/blob/main/config/config_loader.py): `config/config_loader.py`

### Other components

- **Assistant user**

## Connections

- Assistant user → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → FastAPI server: requests
- FastAPI server → Chat controller: routes to (evidence: `api/server.py`)
- Chat controller → Query router: processes query (evidence: `controllers/chat_controller.py`)
- Assistant user → Voice session: speaks to (evidence: `README.md`)
- Voice session → Query router: routes query (evidence: `voice/manager.py`)
- Query router → Intent classifier: classifies with (evidence: `core/router.py`)
- Query router → Local model brain: generates with (evidence: `core/router.py`)
- Query router → Tool registry: dispatches tools (evidence: `core/router.py`)
- Query router → Prompt context: builds context (evidence: `core/router.py`)
- Chat controller → Persistence operations: persists chat (evidence: `controllers/chat_controller.py`)
- Document upload → Document retrieval: indexes documents (evidence: `controllers/upload_controller.py`)
- Document retrieval → Application database: uses database (evidence: `ai/rag/store.py`)
- Prompt context → Document retrieval: retrieves documents (evidence: `core/context.py`)
- Prompt context → Persistence operations: loads history (evidence: `core/context.py`)
- User memory → Persistence operations: reads and writes (evidence: `memory/manager.py`)
- RAG tools → Document retrieval: queries documents (evidence: `tools/rag_tools.py`)
- Graph RAG tools → Graph RAG: invokes retrieval (evidence: `tools/graphrag_tools.py`)
- Graph RAG tools → Knowledge graph: uses graph (evidence: `tools/graphrag_tools.py`)
- Graph RAG → Knowledge graph: queries graph (evidence: `ai/rag/graph_rag.py`)
- Graph RAG → Local model brain: uses model (evidence: `ai/rag/graph_rag.py`)
- Plugin manager → Tool registry: registers tools (evidence: `plugins/manager.py`)
- Persistence operations → Application database: accesses storage (evidence: `database/crud.py`)
- Authentication → Persistence operations: persists sessions (evidence: `controllers/auth_controller.py`)
- FastAPI server → Authentication: routes to (evidence: `api/server.py`)
- FastAPI server → System diagnostics: routes to (evidence: `api/server.py`)
- System diagnostics → Hardware monitor: reads telemetry (evidence: `controllers/system_controller.py`)
- System diagnostics → Intent classifier: tests classifier (evidence: `controllers/system_controller.py`)
- Runtime configuration → Application database: configures storage (evidence: `config/config_loader.py`)