# while-basic/celaya architecture

> Architecture diagram of the GitHub repository while-basic/celaya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/while-basic/celaya
- Repository: https://github.com/while-basic/celaya

## Overview

##### Project type and purpose
- This is a multi-component local LLM platform (“Ollama”) that includes:
- A command-line client (`cmd/`, `main.go`) and desktop UI (`app/`, `macapp/`, `app/tray/`)
- A long-running local daemon or server (`server/`, `llm/`, `ml/`) exposing a REST API
- A model execution engine (wrapping `llama.cpp` via `ml/backend`, `convert/`, `model/`, `kvcache/`, `sample/`)
- File-system and cache management (`fs/`, `server/internal/cache`, `app/store/`)
- External model registry integration (`server/internal/client/ollama`, `api/`)

##### File structure
- Top-level CLI client: `main.go`, `cmd/`, `runner/`.
- Daemon/server: `server/` hosts routes, handlers, internal caches, registry, scheduler.
- Model loader & executor: `convert/`, `ml/backend/ggml`, `model/`, `kvcache/`, `sample/`.
- GPU/CPU discovery: `discover/`.
- UI layers: native tray (`app/tray/`), cross-platform GUI assets (`app/assets/`), Electron/mac app (`macapp/`).
- Configuration & build: `Dockerfile`, `Makefile.sync`, `CMakeLists.txt`, `scripts/`.
- Integration & unit tests sprinkled across modules.

##### Key insights from README
- CLI commands (`ollama run`, `create`, `pull`, `serve`) communicate with a local server (default `localhost:11434`).
- REST API for generate/chat/manage models (`api/`).
- Supports model import (GGUF, Safetensors) via a Modelfile.
- Desktop UX: system tray, native menus.

##### Relationships & interactions
- CLI/Desktop UI → HTTP/gRPC → Local Server
- Server → reads/writes → Local FS (models, blobs, cache)
- Server → HTTP → External Registry (pull/push models)
- Server → In-process calls → Model loader, convertors, inference engine
- Inference engine → native calls → llama.cpp (CPU/GPU backends)
- GPU discovery module → OS/driver APIs → detect hardware capabilities
- Server → Scheduler → dispatch jobs to model runner
- Server → REST API → client SDKs & examples

##### Architectural patterns & design principles
- Layered architecture: Presentation → Application → Domain → Infrastructure
- Modular packages: separation of concerns (convert, model, runner, server, UI)
- Adapter pattern: `ml/backend` and `discover` abstract over hardware backends
- Cache and registry abstractions for pluggable storage backends

##### Technology call-outs
- Go for core implementation
- C/C++ (llama.cpp) bridged via cgo
- Electron/TypeScript for macapp (`macapp/`)
- GGML for inference (`ml/backend/ggml`)
- REST API served by Go’s `net/http` (`server/`)
- File I/O and blob cache (`fs/`, `server/internal/cache/blob`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "CLI Client" 
            CLI_Main["main.go"]:::client
            CLI_Cmd["cmd/"]:::client
            CLI_Runner["cmd/runner/main.go"]:::client
        end
        subgraph "Desktop UI"
            App["app/"]:::client
            Tray["app/tray/"]:::client
            MacApp["macapp/src/"]:::client
        end
        subgraph "SDKs & Examples"
            SDK_Client["api/client.go"]:::client
            SDK_Examples["api/examples/"]:::client
        end
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Local Server / Daemon"
            APIRouter["REST API Router"]:::server
            Scheduler["Scheduler & Orchestration"]:::server
            RegistryClient["Model Registry Client"]:::server
            CacheMod["Cache Module"]:::server
            InferenceEntry["Inference Engine (Entry)"]:::server
        end
    end

    %% Domain & Execution Layer
    subgraph "Domain & Execution Layer"
        subgraph "Execution Engine"
            Convert["Convert & Tokenizer"]:::engine
            ModelParser["Model Parser"]:::engine
            KVCache["KVC Cache"]:::engine
            Sampler["Sampler"]:::engine
            GGML["GGML Backend"]:::engine
        end
        GPUDisc["GPU/CPU Discovery"]:::engine
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        FS["Local Filesystem & Cache"]:::external
        Native["Native Llama.cpp Bridge"]:::external
        ExtReg["External Registry / Docker Hub"]:::external
        OS["OS & Drivers"]:::external
    end

    %% Interactions
    CLI_Main -->|"HTTP/gRPC"| APIRouter
    CLI_Cmd -->|"HTTP/gRPC"| APIRouter
    CLI_Runner -->|"HTTP/gRPC"| APIRouter
    App -->|"HTTP/gRPC"| APIRouter
    Tray -->|"HTTP/gRPC"| APIRouter
    MacApp -->|"HTTP/gRPC"| APIRouter
    SDK_Client -->|"REST API"| APIRouter
    SDK_Examples -->|"REST API"| APIRouter

    APIRouter -->|"schedule jobs"| Scheduler
    APIRouter -->|"manage models"| RegistryClient
    APIRouter -->|"read/write cache"| CacheMod
    APIRouter -->|"invoke inference"| InferenceEntry

    Scheduler -->|"dispatch"| InferenceEntry
    RegistryClient -->|"pull/push"| ExtReg
    CacheMod -->|"store blobs"| FS

    InferenceEntry -->|"convert"| Convert
    Convert -->|"parse model"| ModelParser
    ModelParser -->|"cache kv pairs"| KVCache
    KVCache -->|"sample tokens"| Sampler
    Sampler -->|"run inference"| GGML

    GPUDisc -->|"hardware info"| GGML
    OS -->|"provide drivers"| GPUDisc
    OS -->|"notifications & support"| Tray
    GGML -->|"native calls"| Native

    %% Click Events
    click CLI_Main "https://github.com/while-basic/celaya/blob/main/main.go"
    click CLI_Cmd "https://github.com/while-basic/celaya/tree/main/cmd/"
    click CLI_Runner "https://github.com/while-basic/celaya/blob/main/cmd/runner/main.go"
    click App "https://github.com/while-basic/celaya/tree/main/app/"
    click Tray "https://github.com/while-basic/celaya/tree/main/app/tray/"
    click MacApp "https://github.com/while-basic/celaya/tree/main/macapp/src/"
    click SDK_Client "https://github.com/while-basic/celaya/blob/main/api/client.go"
    click SDK_Examples "https://github.com/while-basic/celaya/tree/main/api/examples/"
    click APIRouter "https://github.com/while-basic/celaya/blob/main/server/routes.go"
    click Scheduler "https://github.com/while-basic/celaya/blob/main/server/sched.go"
    click RegistryClient "https://github.com/while-basic/celaya/blob/main/server/internal/registry/server.go"
    click CacheMod "https://github.com/while-basic/celaya/tree/main/server/internal/cache/blob/"
    click Convert "https://github.com/while-basic/celaya/tree/main/convert/"
    click ModelParser "https://github.com/while-basic/celaya/tree/main/model/"
    click KVCache "https://github.com/while-basic/celaya/tree/main/kvcache/"
    click Sampler "https://github.com/while-basic/celaya/tree/main/sample/"
    click GGML "https://github.com/while-basic/celaya/tree/main/ml/backend/ggml/"
    click GPUDisc "https://github.com/while-basic/celaya/tree/main/discover/"
    click FS "https://github.com/while-basic/celaya/tree/main/fs/"
    click Native "https://github.com/while-basic/celaya/tree/main/llama/"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,color:#000
    classDef server fill:#90EE90,stroke:#000,color:#000
    classDef engine fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#D3D3D3,stroke:#000,color:#000
```
