# va-desai-dev/engraiserver architecture

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

- Interactive diagram: https://gitdiagram.com/va-desai-dev/engraiserver
- Repository: https://github.com/va-desai-dev/engraiserver

## Overview

ENGRAISERVER hosts local text and image inference behind an authenticated gateway and browser console. The main workflow is console sign-in and model selection, gateway orchestration of profiles and a private engine worker, then inference responses to clients. Separate product branches provide model discovery/downloads, Ledger memory, Card Studio authoring, and SymLink sharing. Edges follow shown imports/calls or README descriptions; several unsampled subsystems are represented at their supported paths, with only documented or clearly evidenced relationships drawn.

Main entry points: [`src/engrai_server/main.py`](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/main.py) (HTTP Gateway), [`ui/src/modes/Control.tsx`](https://github.com/va-desai-dev/engraiserver/blob/master/ui/src/modes/Control.tsx) (Web Console), [`src/engrai_server/cardgen/router.py`](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/router.py) (Card Studio), [`src/engrai_server/ledger/service.py`](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/service.py) (Ledger Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Console and Gateway"]
  node_console["Web Console<br/>[Control.tsx]"]
  node_api["API Client<br/>[api.ts]"]
  node_gateway["HTTP Gateway<br/>[main.py]"]
  node_auth["Session Auth<br/>[auth.py]"]
end

subgraph group_models["Models and Engines"]
  node_profiles["Model Profiles<br/>[profiles.py]"]
  node_deployments["Deployment Contracts<br/>[deployments.py]"]
  node_text["Text Inference<br/>[llamacpp.py]"]
  node_image["Image Inference<br/>[image_engine.py]"]
  node_worker["Worker Supervision<br/>[worker.py]"]
  node_modelhub["Model Browser and Pulls<br/>[model_downloads.py]"]
end

subgraph group_features["Inference Features"]
  node_cardstudio["Card Studio<br/>[router.py]"]
  node_cardlibrary[("Card Library<br/>[store.py]")]
  node_cardweb["Card Studio Browser<br/>[main.js]"]
end

subgraph group_memory["Ledger"]
  node_ledgerapi["Ledger API<br/>[router.py]"]
  node_ledger["Ledger Service<br/>[service.py]"]
  node_ledgerindex[("Recall Index<br/>[index.py]")]
end

subgraph group_sharing["Cards and Sharing"]
  node_symrouter["SymLink API<br/>[router.py]"]
  node_symstore[("Peer Store<br/>[store.py]")]
end

node_operator(("Operator"))
node_clients(("Chat and Image Clients"))

node_operator -->|"uses"| node_console
node_console -->|"requests"| node_api
node_api -->|"calls endpoints"| node_gateway
node_gateway -->|"checks sessions"| node_auth
node_gateway -->|"reads profiles"| node_profiles
node_profiles -->|"uses contracts"| node_deployments
node_gateway -->|"routes text"| node_text
node_gateway -->|"routes images"| node_image
node_text -->|"supervises worker"| node_worker
node_image -->|"supervises worker"| node_worker
node_clients -->|"sends inference"| node_gateway
node_console -.->|"browses and downloads"| node_modelhub
node_gateway -.->|"serves model tools"| node_modelhub
node_gateway -->|"mounts routes"| node_cardstudio
node_cardstudio -->|"reads and writes"| node_cardlibrary
node_cardweb -.->|"calls API"| node_cardstudio
node_gateway -->|"mounts routes"| node_ledgerapi
node_ledgerapi -->|"delegates"| node_ledger
node_ledger -->|"reads and writes"| node_ledgerindex
node_gateway -->|"injects recall"| node_ledger
node_gateway -->|"mounts routes"| node_symrouter
node_symrouter -->|"reads and writes"| node_symstore

click node_console "https://github.com/va-desai-dev/engraiserver/blob/master/ui/src/modes/Control.tsx"
click node_api "https://github.com/va-desai-dev/engraiserver/blob/master/ui/src/lib/api.ts"
click node_gateway "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/main.py"
click node_auth "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/auth.py"
click node_profiles "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/profiles.py"
click node_deployments "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/domain/deployments.py"
click node_text "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/llamacpp.py"
click node_image "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/image_engine.py"
click node_worker "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/engines/worker.py"
click node_modelhub "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/model_downloads.py"
click node_cardstudio "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/router.py"
click node_cardlibrary "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/store.py"
click node_ledgerapi "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/router.py"
click node_ledger "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/service.py"
click node_ledgerindex "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/index.py"
click node_symrouter "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/symlink/router.py"
click node_symstore "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/symlink/store.py"
click node_cardweb "https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/web/src/scripts/main.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_console,node_api,node_gateway,node_auth,node_clients toneBlue
class node_profiles,node_deployments,node_text,node_image,node_worker,node_modelhub toneAmber
class node_cardstudio,node_cardlibrary,node_cardweb toneMint
class node_ledgerapi,node_ledger,node_ledgerindex toneRose
class node_symrouter,node_symstore,node_operator toneIndigo
```

## Components

### Console and Gateway

- [Web Console](https://github.com/va-desai-dev/engraiserver/blob/master/ui/src/modes/Control.tsx): `ui/src/modes/Control.tsx`
- [API Client](https://github.com/va-desai-dev/engraiserver/blob/master/ui/src/lib/api.ts): `ui/src/lib/api.ts`
- [HTTP Gateway](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/main.py): `src/engrai_server/main.py`
- [Session Auth](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/auth.py): `src/engrai_server/auth.py`

### Models and Engines

- [Model Profiles](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/profiles.py): `src/engrai_server/profiles.py`
- [Deployment Contracts](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/domain/deployments.py): `src/engrai_server/domain/deployments.py`
- [Text Inference](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/llamacpp.py): `src/engrai_server/llamacpp.py`
- [Image Inference](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/image_engine.py): `src/engrai_server/image_engine.py`
- [Worker Supervision](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/engines/worker.py): `src/engrai_server/engines/worker.py`
- [Model Browser and Pulls](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/model_downloads.py): `src/engrai_server/model_downloads.py`

### Inference Features

- [Card Studio](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/router.py): `src/engrai_server/cardgen/router.py`
- [Card Library](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/store.py): `src/engrai_server/cardgen/store.py`
- [Card Studio Browser](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/cardgen/web/src/scripts/main.js): `src/engrai_server/cardgen/web/src/scripts/main.js`

### Ledger

- [Ledger API](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/router.py): `src/engrai_server/ledger/router.py`
- [Ledger Service](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/service.py): `src/engrai_server/ledger/service.py`
- [Recall Index](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/ledger/index.py): `src/engrai_server/ledger/index.py`

### Cards and Sharing

- [SymLink API](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/symlink/router.py): `src/engrai_server/symlink/router.py`
- [Peer Store](https://github.com/va-desai-dev/engraiserver/blob/master/src/engrai_server/symlink/store.py): `src/engrai_server/symlink/store.py`

### Other components

- **Operator**
- **Chat and Image Clients**

## Connections

- Operator → Web Console: uses (evidence: `README.md`)
- Web Console → API Client: requests (evidence: `ui/src/modes/Control.tsx`)
- API Client → HTTP Gateway: calls endpoints (evidence: `ui/src/lib/api.ts`)
- HTTP Gateway → Session Auth: checks sessions (evidence: `src/engrai_server/main.py`)
- HTTP Gateway → Model Profiles: reads profiles (evidence: `src/engrai_server/main.py`)
- Model Profiles → Deployment Contracts: uses contracts (evidence: `src/engrai_server/profiles.py`)
- HTTP Gateway → Text Inference: routes text (evidence: `src/engrai_server/main.py`)
- HTTP Gateway → Image Inference: routes images (evidence: `src/engrai_server/main.py`)
- Text Inference → Worker Supervision: supervises worker (evidence: `src/engrai_server/llamacpp.py`)
- Image Inference → Worker Supervision: supervises worker (evidence: `src/engrai_server/image_engine.py`)
- Chat and Image Clients → HTTP Gateway: sends inference (evidence: `README.md`)
- Web Console → Model Browser and Pulls: browses and downloads
- HTTP Gateway → Model Browser and Pulls: serves model tools (evidence: `src/engrai_server/main.py`)
- HTTP Gateway → Card Studio: mounts routes (evidence: `src/engrai_server/main.py`)
- Card Studio → Card Library: reads and writes (evidence: `src/engrai_server/cardgen/router.py`)
- Card Studio Browser → Card Studio: calls API
- HTTP Gateway → Ledger API: mounts routes (evidence: `src/engrai_server/main.py`)
- Ledger API → Ledger Service: delegates (evidence: `src/engrai_server/ledger/router.py`)
- Ledger Service → Recall Index: reads and writes (evidence: `src/engrai_server/ledger/service.py`)
- HTTP Gateway → Ledger Service: injects recall
- HTTP Gateway → SymLink API: mounts routes (evidence: `src/engrai_server/main.py`)
- SymLink API → Peer Store: reads and writes (evidence: `src/engrai_server/symlink/router.py`)