# nav477/project-nomad architecture

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

- Interactive diagram: https://gitdiagram.com/nav477/project-nomad
- Repository: https://github.com/nav477/project-nomad

## Overview

Project NOMAD is an offline-first browser-accessible knowledge and education server. Users access the Command Center to install and manage services, explore offline content, use AI chat with uploaded documents, and configure system features; the backend coordinates containerized tools and resources. The graph also preserves documented capabilities for maps, education, Supply Depot, updates, setup, and benchmarking. Some subsystem links are documented only at product level; dashed edges mark links whose implementation wiring was not shown in the sampled source.

Main entry points: [`admin/app/services/rag_service.ts`](https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_service.ts) (Knowledge indexing and search), [`admin/app/services/rag_pipeline_service.ts`](https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_pipeline_service.ts) (RAG pipeline), [`admin/inertia/pages/home.tsx`](https://github.com/nav477/project-nomad/blob/main/admin/inertia/pages/home.tsx) (Command Center UI), [`admin/app/controllers/system_controller.ts`](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/system_controller.ts) (Service management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Command Center"]
  node_command_ui["Command Center UI<br/>[home.tsx]"]
  node_service_api["Service management API"]
  node_chat_api["AI chat API"]
  node_rag_api["Knowledge API<br/>[rag_controller.ts]"]
  node_setup["Easy setup wizard"]
end

subgraph group_knowledge["Knowledge and AI"]
  node_rag_pipeline["RAG pipeline"]
  node_rag_service["Knowledge indexing and search<br/>[rag_service.ts]"]
  node_uploads[("Document storage<br/>[fs.ts]")]
  node_ollama["Model management<br/>[ollama_service.ts]"]
  node_qdrant[("Qdrant vector store")]
  node_kiwix["Offline information library"]
end

subgraph group_services["Managed Services"]
  node_docker["Docker services<br/>[docker_service.ts]"]
  node_service_catalog[("Service catalog<br/>[service_seeder.ts]")]
  node_maps["Offline maps<br/>[map_service.ts]"]
  node_supply["Supply Depot"]
  node_education["Education platform"]
  node_data_tools["Data tools and notes"]
end

subgraph group_operations["System Operations"]
  node_updates["Automatic updates"]
  node_benchmark["System benchmark"]
  node_system_info["System information<br/>[system_service.ts]"]
end

node_browser(("Browser user"))

node_browser -->|"uses"| node_command_ui
node_command_ui -.->|"manages services"| node_service_api
node_service_api -->|"orchestrates"| node_docker
node_service_catalog -.->|"defines services"| node_docker
node_browser -->|"asks questions"| node_chat_api
node_chat_api -.->|"runs chat"| node_rag_pipeline
node_browser -->|"uploads documents"| node_rag_api
node_rag_api -->|"delegates to"| node_rag_service
node_rag_pipeline -->|"searches with"| node_rag_service
node_rag_pipeline -->|"requests models"| node_ollama
node_rag_service -->|"queries vectors"| node_qdrant
node_rag_service -->|"reads files"| node_uploads
node_browser -->|"reads offline content"| node_kiwix
node_browser -->|"explores maps"| node_maps
node_browser -->|"takes courses"| node_education
node_browser -->|"uses tools"| node_data_tools
node_browser -->|"browses catalog"| node_supply
node_browser -->|"configures NOMAD"| node_setup
node_browser -->|"configures updates"| node_updates
node_browser -->|"runs benchmark"| node_benchmark
node_browser -.->|"checks system"| node_system_info

click node_command_ui "https://github.com/nav477/project-nomad/blob/main/admin/inertia/pages/home.tsx"
click node_service_api "https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/system_controller.ts"
click node_chat_api "https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/chats_controller.ts"
click node_rag_api "https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/rag_controller.ts"
click node_rag_pipeline "https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_pipeline_service.ts"
click node_rag_service "https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_service.ts"
click node_uploads "https://github.com/nav477/project-nomad/blob/main/admin/app/utils/fs.ts"
click node_ollama "https://github.com/nav477/project-nomad/blob/main/admin/app/services/ollama_service.ts"
click node_kiwix "https://github.com/nav477/project-nomad/blob/main/admin/app/services/kiwix_library_service.ts"
click node_docker "https://github.com/nav477/project-nomad/blob/main/admin/app/services/docker_service.ts"
click node_service_catalog "https://github.com/nav477/project-nomad/blob/main/admin/database/seeders/service_seeder.ts"
click node_maps "https://github.com/nav477/project-nomad/blob/main/admin/app/services/map_service.ts"
click node_supply "https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/supply_depot_controller.ts"
click node_setup "https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/easy_setup_controller.ts"
click node_updates "https://github.com/nav477/project-nomad/blob/main/admin/app/services/content_auto_update_service.ts"
click node_benchmark "https://github.com/nav477/project-nomad/blob/main/admin/app/services/benchmark_service.ts"
click node_system_info "https://github.com/nav477/project-nomad/blob/main/admin/app/services/system_service.ts"

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_command_ui,node_service_api,node_chat_api,node_rag_api,node_setup,node_browser toneBlue
class node_rag_pipeline,node_rag_service,node_uploads,node_ollama,node_qdrant,node_kiwix toneAmber
class node_docker,node_service_catalog,node_maps,node_supply,node_education,node_data_tools toneMint
class node_updates,node_benchmark,node_system_info toneRose
```

## Components

### Command Center

- [Command Center UI](https://github.com/nav477/project-nomad/blob/main/admin/inertia/pages/home.tsx): `admin/inertia/pages/home.tsx`
- [Service management API](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/system_controller.ts): `admin/app/controllers/system_controller.ts`
- [AI chat API](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/chats_controller.ts): `admin/app/controllers/chats_controller.ts`
- [Knowledge API](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/rag_controller.ts): `admin/app/controllers/rag_controller.ts`
- [Easy setup wizard](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/easy_setup_controller.ts): `admin/app/controllers/easy_setup_controller.ts`

### Knowledge and AI

- [RAG pipeline](https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_pipeline_service.ts): `admin/app/services/rag_pipeline_service.ts`
- [Knowledge indexing and search](https://github.com/nav477/project-nomad/blob/main/admin/app/services/rag_service.ts): `admin/app/services/rag_service.ts`
- [Document storage](https://github.com/nav477/project-nomad/blob/main/admin/app/utils/fs.ts): `admin/app/utils/fs.ts`
- [Model management](https://github.com/nav477/project-nomad/blob/main/admin/app/services/ollama_service.ts): `admin/app/services/ollama_service.ts`
- **Qdrant vector store**
- [Offline information library](https://github.com/nav477/project-nomad/blob/main/admin/app/services/kiwix_library_service.ts): `admin/app/services/kiwix_library_service.ts`

### Managed Services

- [Docker services](https://github.com/nav477/project-nomad/blob/main/admin/app/services/docker_service.ts): `admin/app/services/docker_service.ts`
- [Service catalog](https://github.com/nav477/project-nomad/blob/main/admin/database/seeders/service_seeder.ts): `admin/database/seeders/service_seeder.ts`
- [Offline maps](https://github.com/nav477/project-nomad/blob/main/admin/app/services/map_service.ts): `admin/app/services/map_service.ts`
- [Supply Depot](https://github.com/nav477/project-nomad/blob/main/admin/app/controllers/supply_depot_controller.ts): `admin/app/controllers/supply_depot_controller.ts`
- **Education platform**
- **Data tools and notes**

### System Operations

- [Automatic updates](https://github.com/nav477/project-nomad/blob/main/admin/app/services/content_auto_update_service.ts): `admin/app/services/content_auto_update_service.ts`
- [System benchmark](https://github.com/nav477/project-nomad/blob/main/admin/app/services/benchmark_service.ts): `admin/app/services/benchmark_service.ts`
- [System information](https://github.com/nav477/project-nomad/blob/main/admin/app/services/system_service.ts): `admin/app/services/system_service.ts`

### Other components

- **Browser user**

## Connections

- Browser user → Command Center UI: uses (evidence: `README.md`)
- Command Center UI → Service management API: manages services
- Service management API → Docker services: orchestrates (evidence: `README.md`)
- Service catalog → Docker services: defines services
- Browser user → AI chat API: asks questions (evidence: `README.md`)
- AI chat API → RAG pipeline: runs chat
- Browser user → Knowledge API: uploads documents (evidence: `README.md`)
- Knowledge API → Knowledge indexing and search: delegates to (evidence: `admin/app/controllers/rag_controller.ts`)
- RAG pipeline → Knowledge indexing and search: searches with (evidence: `admin/app/services/rag_pipeline_service.ts`)
- RAG pipeline → Model management: requests models (evidence: `admin/app/services/rag_pipeline_service.ts`)
- Knowledge indexing and search → Qdrant vector store: queries vectors (evidence: `admin/app/services/rag_service.ts`)
- Knowledge indexing and search → Document storage: reads files (evidence: `admin/app/services/rag_service.ts`)
- Browser user → Offline information library: reads offline content (evidence: `README.md`)
- Browser user → Offline maps: explores maps (evidence: `README.md`)
- Browser user → Education platform: takes courses (evidence: `README.md`)
- Browser user → Data tools and notes: uses tools (evidence: `README.md`)
- Browser user → Supply Depot: browses catalog (evidence: `README.md`)
- Browser user → Easy setup wizard: configures NOMAD (evidence: `README.md`)
- Browser user → Automatic updates: configures updates (evidence: `README.md`)
- Browser user → System benchmark: runs benchmark (evidence: `README.md`)
- Browser user → System information: checks system
