# medhiclb/helixai architecture

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

- Interactive diagram: https://gitdiagram.com/medhiclb/helixai
- Repository: https://github.com/medhiclb/helixai

## Overview

Helix AI is a local-first desktop AI workspace for individuals and organisations. The principal workflow is to bring a question and optional documents to Chat, use a selected local or explicitly configured cloud model—optionally with knowledge-base context—and receive a sourced answer. The product also supports coding, persistent agents and scheduled tasks, model fine-tuning, team administration, and user-connected services. The graph combines README-documented capabilities with paths and relationships visible in the supplied source index and excerpts; unsampled implementation details are not inferred.

Main entry points: [`gateway/src/index.ts`](https://github.com/medhiclb/helixai/blob/main/gateway/src/index.ts) (Gateway API), [`src/App.tsx`](https://github.com/medhiclb/helixai/blob/main/src/App.tsx) (Application routing), [`gateway/src/chat.ts`](https://github.com/medhiclb/helixai/blob/main/gateway/src/chat.ts) (Chat service), [`gateway/src/atelier.ts`](https://github.com/medhiclb/helixai/blob/main/gateway/src/atelier.ts) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop experience"]
  node_app["Application routing<br/>[App.tsx]"]
  node_chat["Chat experience"]
  node_coding["Coding workspace<br/>[CodePage.tsx]"]
  node_agents_ui["Agents workspace<br/>[AgentsPage.tsx]"]
  node_library_ui["Knowledge library"]
  node_task_ui["Task board<br/>[TachesPage.tsx]"]
  node_branding["Product configuration<br/>[branding.ts]"]
end

subgraph group_ai["AI and knowledge"]
  node_chat_service["Chat service<br/>[chat.ts]"]
  node_models["Model backends<br/>[backends.ts]"]
  node_engine["Local engine setup<br/>[engine.ts]"]
  node_knowledge["Knowledge bases<br/>[bibliotheque.ts]"]
  node_training["Model fine-tuning<br/>[entrainement.ts]"]
end

subgraph group_work["Work automation"]
  node_code_service["Code execution"]
  node_agent_service["Agent runtime<br/>[atelier.ts]"]
  node_tasks["Scheduled missions"]
end

subgraph group_services["Services and teams"]
  node_connectors["Connected services<br/>[connecteurs.ts]"]
  node_teams["Accounts and groups<br/>[accounts.ts]"]
  node_security["Access and audit<br/>[authz.ts]"]
  node_protected["Protected zones<br/>[zonesProtegees.ts]"]
end

subgraph group_runtime["Runtime and state"]
  node_gateway["Gateway API<br/>[index.ts]"]
  node_db[("Instance database<br/>[db.ts]")]
  node_identity["Client identity<br/>[identity.ts]"]
  node_storage["Client persistence<br/>[storage.ts]"]
  node_sync["Instance sync<br/>[sync.ts]"]
  node_desktop["Electron host<br/>[main.cjs]"]
  node_language["Gateway language<br/>[langue.ts]"]
end

node_person(("Person"))

node_person -->|"uses"| node_app
node_app -->|"routes to"| node_chat
node_app -->|"routes to"| node_coding
node_app -->|"routes to"| node_agents_ui
node_app -->|"routes to"| node_library_ui
node_app -->|"routes to"| node_task_ui
node_chat -.->|"sends requests"| node_chat_service
node_chat_service -->|"selects model"| node_models
node_chat_service -->|"uses context"| node_knowledge
node_person -->|"adds documents"| node_knowledge
node_person -->|"trains model"| node_training
node_person -->|"works in"| node_coding
node_person -->|"configures agents"| node_agent_service
node_agents_ui -.->|"manages agents"| node_agent_service
node_task_ui -->|"manages tasks"| node_tasks
node_agent_service -->|"runs missions"| node_tasks
node_person -->|"connects services"| node_connectors
node_person -->|"uses team features"| node_teams
node_teams -->|"uses access controls"| node_security
node_gateway -->|"routes requests"| node_chat_service
node_gateway -->|"routes requests"| node_knowledge
node_gateway -->|"routes requests"| node_training
node_gateway -->|"routes requests"| node_connectors
node_gateway -->|"routes requests"| node_teams
node_gateway -->|"routes requests"| node_security
node_models -.->|"may use local engine"| node_engine
node_identity -->|"reads and writes"| node_storage
node_storage -->|"pushes changes"| node_sync
node_sync -->|"synchronizes with"| node_gateway
node_gateway -.->|"persists data"| node_db
node_desktop -.->|"hosts interface"| node_app
node_branding -->|"configures features"| node_app
node_gateway -->|"uses language context"| node_language
node_gateway -->|"uses protected zones"| node_protected

click node_app "https://github.com/medhiclb/helixai/blob/main/src/App.tsx"
click node_chat "https://github.com/medhiclb/helixai/tree/main/src/components/chat"
click node_coding "https://github.com/medhiclb/helixai/blob/main/src/pages/CodePage.tsx"
click node_agents_ui "https://github.com/medhiclb/helixai/blob/main/src/pages/AgentsPage.tsx"
click node_library_ui "https://github.com/medhiclb/helixai/blob/main/src/pages/BibliothequePage.tsx"
click node_task_ui "https://github.com/medhiclb/helixai/blob/main/src/pages/TachesPage.tsx"
click node_gateway "https://github.com/medhiclb/helixai/blob/main/gateway/src/index.ts"
click node_chat_service "https://github.com/medhiclb/helixai/blob/main/gateway/src/chat.ts"
click node_models "https://github.com/medhiclb/helixai/blob/main/gateway/src/backends.ts"
click node_engine "https://github.com/medhiclb/helixai/blob/main/gateway/src/engine.ts"
click node_knowledge "https://github.com/medhiclb/helixai/blob/main/gateway/src/bibliotheque.ts"
click node_training "https://github.com/medhiclb/helixai/blob/main/gateway/src/entrainement.ts"
click node_agent_service "https://github.com/medhiclb/helixai/blob/main/gateway/src/atelier.ts"
click node_tasks "https://github.com/medhiclb/helixai/blob/main/gateway/src/tachesProgrammees.ts"
click node_connectors "https://github.com/medhiclb/helixai/blob/main/gateway/src/connecteurs.ts"
click node_teams "https://github.com/medhiclb/helixai/blob/main/gateway/src/accounts.ts"
click node_security "https://github.com/medhiclb/helixai/blob/main/gateway/src/authz.ts"
click node_db "https://github.com/medhiclb/helixai/blob/main/gateway/src/db.ts"
click node_identity "https://github.com/medhiclb/helixai/blob/main/src/lib/store/identity.ts"
click node_storage "https://github.com/medhiclb/helixai/blob/main/src/lib/store/storage.ts"
click node_sync "https://github.com/medhiclb/helixai/blob/main/src/lib/store/sync.ts"
click node_desktop "https://github.com/medhiclb/helixai/blob/main/electron/main.cjs"
click node_branding "https://github.com/medhiclb/helixai/blob/main/src/config/branding.ts"
click node_language "https://github.com/medhiclb/helixai/blob/main/gateway/src/langue.ts"
click node_protected "https://github.com/medhiclb/helixai/blob/main/gateway/src/zonesProtegees.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_app,node_chat,node_coding,node_agents_ui,node_library_ui,node_task_ui,node_branding toneBlue
class node_chat_service,node_models,node_engine,node_knowledge,node_training toneAmber
class node_code_service,node_agent_service,node_tasks toneMint
class node_connectors,node_teams,node_security,node_protected toneRose
class node_gateway,node_db,node_identity,node_storage,node_sync,node_desktop,node_language,node_person toneIndigo
```

## Components

### Desktop experience

- [Application routing](https://github.com/medhiclb/helixai/blob/main/src/App.tsx): `src/App.tsx`
- [Chat experience](https://github.com/medhiclb/helixai/tree/main/src/components/chat): `src/components/chat`
- [Coding workspace](https://github.com/medhiclb/helixai/blob/main/src/pages/CodePage.tsx): `src/pages/CodePage.tsx`
- [Agents workspace](https://github.com/medhiclb/helixai/blob/main/src/pages/AgentsPage.tsx): `src/pages/AgentsPage.tsx`
- [Knowledge library](https://github.com/medhiclb/helixai/blob/main/src/pages/BibliothequePage.tsx): `src/pages/BibliothequePage.tsx`
- [Task board](https://github.com/medhiclb/helixai/blob/main/src/pages/TachesPage.tsx): `src/pages/TachesPage.tsx`
- [Product configuration](https://github.com/medhiclb/helixai/blob/main/src/config/branding.ts): `src/config/branding.ts`

### AI and knowledge

- [Chat service](https://github.com/medhiclb/helixai/blob/main/gateway/src/chat.ts): `gateway/src/chat.ts`
- [Model backends](https://github.com/medhiclb/helixai/blob/main/gateway/src/backends.ts): `gateway/src/backends.ts`
- [Local engine setup](https://github.com/medhiclb/helixai/blob/main/gateway/src/engine.ts): `gateway/src/engine.ts`
- [Knowledge bases](https://github.com/medhiclb/helixai/blob/main/gateway/src/bibliotheque.ts): `gateway/src/bibliotheque.ts`
- [Model fine-tuning](https://github.com/medhiclb/helixai/blob/main/gateway/src/entrainement.ts): `gateway/src/entrainement.ts`

### Work automation

- **Code execution**
- [Agent runtime](https://github.com/medhiclb/helixai/blob/main/gateway/src/atelier.ts): `gateway/src/atelier.ts`
- [Scheduled missions](https://github.com/medhiclb/helixai/blob/main/gateway/src/tachesProgrammees.ts): `gateway/src/tachesProgrammees.ts`

### Services and teams

- [Connected services](https://github.com/medhiclb/helixai/blob/main/gateway/src/connecteurs.ts): `gateway/src/connecteurs.ts`
- [Accounts and groups](https://github.com/medhiclb/helixai/blob/main/gateway/src/accounts.ts): `gateway/src/accounts.ts`
- [Access and audit](https://github.com/medhiclb/helixai/blob/main/gateway/src/authz.ts): `gateway/src/authz.ts`
- [Protected zones](https://github.com/medhiclb/helixai/blob/main/gateway/src/zonesProtegees.ts): `gateway/src/zonesProtegees.ts`

### Runtime and state

- [Gateway API](https://github.com/medhiclb/helixai/blob/main/gateway/src/index.ts): `gateway/src/index.ts`
- [Instance database](https://github.com/medhiclb/helixai/blob/main/gateway/src/db.ts): `gateway/src/db.ts`
- [Client identity](https://github.com/medhiclb/helixai/blob/main/src/lib/store/identity.ts): `src/lib/store/identity.ts`
- [Client persistence](https://github.com/medhiclb/helixai/blob/main/src/lib/store/storage.ts): `src/lib/store/storage.ts`
- [Instance sync](https://github.com/medhiclb/helixai/blob/main/src/lib/store/sync.ts): `src/lib/store/sync.ts`
- [Electron host](https://github.com/medhiclb/helixai/blob/main/electron/main.cjs): `electron/main.cjs`
- [Gateway language](https://github.com/medhiclb/helixai/blob/main/gateway/src/langue.ts): `gateway/src/langue.ts`

### Other components

- **Person**

## Connections

- Person → Application routing: uses (evidence: `README.md`)
- Application routing → Chat experience: routes to (evidence: `src/App.tsx`)
- Application routing → Coding workspace: routes to (evidence: `src/App.tsx`)
- Application routing → Agents workspace: routes to (evidence: `src/App.tsx`)
- Application routing → Knowledge library: routes to (evidence: `src/App.tsx`)
- Application routing → Task board: routes to (evidence: `src/App.tsx`)
- Chat experience → Chat service: sends requests
- Chat service → Model backends: selects model (evidence: `README.md`)
- Chat service → Knowledge bases: uses context (evidence: `README.md`)
- Person → Knowledge bases: adds documents (evidence: `README.md`)
- Person → Model fine-tuning: trains model (evidence: `README.md`)
- Person → Coding workspace: works in (evidence: `README.md`)
- Person → Agent runtime: configures agents (evidence: `README.md`)
- Agents workspace → Agent runtime: manages agents
- Task board → Scheduled missions: manages tasks (evidence: `README.md`)
- Agent runtime → Scheduled missions: runs missions (evidence: `README.md`)
- Person → Connected services: connects services (evidence: `README.md`)
- Person → Accounts and groups: uses team features (evidence: `README.md`)
- Accounts and groups → Access and audit: uses access controls (evidence: `README.md`)
- Gateway API → Chat service: routes requests (evidence: `gateway/src/index.ts`)
- Gateway API → Knowledge bases: routes requests (evidence: `gateway/src/index.ts`)
- Gateway API → Model fine-tuning: routes requests (evidence: `gateway/src/index.ts`)
- Gateway API → Connected services: routes requests (evidence: `gateway/src/index.ts`)
- Gateway API → Accounts and groups: routes requests (evidence: `gateway/src/index.ts`)
- Gateway API → Access and audit: routes requests (evidence: `gateway/src/index.ts`)
- Model backends → Local engine setup: may use local engine
- Client identity → Client persistence: reads and writes (evidence: `src/lib/store/identity.ts`)
- Client persistence → Instance sync: pushes changes (evidence: `src/lib/store/storage.ts`)
- Instance sync → Gateway API: synchronizes with (evidence: `src/lib/store/sync.ts`)
- Gateway API → Instance database: persists data (evidence: `gateway/src/index.ts`)
- Electron host → Application routing: hosts interface
- Product configuration → Application routing: configures features (evidence: `src/App.tsx`)
- Gateway API → Gateway language: uses language context (evidence: `gateway/src/index.ts`)
- Gateway API → Protected zones: uses protected zones (evidence: `gateway/src/index.ts`)
