# techjarves/odysseus-portable architecture

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

- Interactive diagram: https://gitdiagram.com/techjarves/odysseus-portable
- Repository: https://github.com/techjarves/odysseus-portable

## Overview

1. **This repo is a portable launcher/orchestrator, not the AI app itself.**  
   Its job is to prepare a self-contained local environment, then start the Odysseus web UI and a local model server on localhost.

2. **The entry points are OS-specific shell wrappers.**  
   `start.bat` and `start.sh` kick off the Node-based launcher. The `scripts/` folder also contains bootstrap/reset helpers, including a PowerShell bootstrapper for Windows.

3. **`src/start.js` is the main control plane.**  
   It is the top-level orchestrator that sequences startup: environment checks, runtime provisioning, model selection, backend launch, and browser opening.

4. **`src/system.js` is the hardware and platform detection boundary.**  
   It scans the host OS and machine capabilities so the launcher can choose the correct portable binaries and size/shape the inference runtime for the device.

5. **`src/downloader.js` handles portable dependency acquisition.**  
   The launcher downloads and extracts bundled runtimes on demand rather than relying on system-installed Node, Python, or model-server binaries.

6. **`src/model.js` manages local GGUF model discovery and retrieval.**  
   This is the model boundary: it scans the `models/` area, supports local selection, and downloads model artifacts when needed.

7. **`src/runtime.js` manages child processes and lifecycle.**  
   It appears to be the process supervisor for the launched services, including startup, shutdown, logging, and restart behavior when a backend fails.

8. **`src/backends/` contains inference adapters.**  
   There are separate backend implementations for `llama` and `ollama`, with `common.js` shared across them. This suggests the launcher can target more than one local model-serving stack.

9. **`src/backends/common.js` is the initialization/seed layer.**  
   The README indicates it sets up database credentials and performs self-healing setup work, so this is likely where Odysseus-specific bootstrapping and SQLite-related setup happen.

10. **`src/backends/llama/` is the main llama.cpp integration path.**  
    The README centers on a local `llama-server` backend serving GGUF models, with the launcher selecting context size and parallelism based on hardware.

11. **`src/backends/ollama/` provides an alternate local model backend.**  
    Even though the README focuses on llama.cpp, the tree shows explicit Ollama support, so the architecture includes a second inference adapter rather than a single hard-coded engine.

12. **The external Odysseus web application is a separate repository/runtime boundary.**  
    The launcher clones or updates the `./odysseus` repo and then runs it locally. That web app is the user-facing interface, while this repo provides the environment and model services beneath it.

13. **The main runtime flow is local and offline-first.**  
    Startup checks hardware, provisions portable runtimes, updates or seeds the app, starts the model backend, starts the web UI, and opens `http://127.0.0.1:7070`. The model API is exposed only on localhost, with an additional proxy/backend port in the 8080/10086 range per the README.

14. **All persistent state stays inside the project directory.**  
    The architecture intentionally keeps binaries under `bin/`, models under `models/`, the cloned app under `odysseus/`, and logs under `logs/`, so the entire workspace is portable and leaves minimal host-system footprint.

Main entry points: [`src/start.js`](https://github.com/techjarves/odysseus-portable/blob/main/src/start.js) (start.js), [`src/backends/common.js`](https://github.com/techjarves/odysseus-portable/blob/main/src/backends/common.js) (common.js), [`src/downloader.js`](https://github.com/techjarves/odysseus-portable/blob/main/src/downloader.js) (downloader.js), [`src/model.js`](https://github.com/techjarves/odysseus-portable/blob/main/src/model.js) (model.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launchers["Launchers"]
  node_start_bat["start.bat<br/>entry script<br/>[start.bat]"]
  node_start_sh["start.sh<br/>entry script<br/>[start.sh]"]
  node_bootstrap_ps1["bootstrap-node.ps1<br/>bootstrap script<br/>[bootstrap-node.ps1]"]
  node_reset_scripts["reset helpers<br/>maintenance scripts"]
end

subgraph group_core["Core Orchestration"]
  node_start_js["start.js<br/>orchestrator<br/>[start.js]"]
  node_system_js["system.js<br/>platform probe<br/>[system.js]"]
  node_downloader_js["downloader.js<br/>artifact fetcher<br/>[downloader.js]"]
  node_model_js["model.js<br/>model manager<br/>[model.js]"]
  node_runtime_js["runtime.js<br/>process supervisor<br/>[runtime.js]"]
  node_git_bootstrap["git bootstrap<br/>repo seeding<br/>[git.js]"]
end

subgraph group_backends["Backends"]
  node_backend_common["common.js<br/>backend setup<br/>[common.js]"]
  node_llama_backend["llama backend<br/>llama adapter<br/>[index.js]"]
  node_ollama_backend["ollama backend<br/>ollama adapter<br/>[index.js]"]
end

subgraph group_state["Workspace State"]
  node_odysseus_repo[("odysseus repo<br/>external web app")]
  node_bin_dir[("bin/<br/>portable runtimes")]
  node_models_dir[("models/<br/>model cache")]
  node_logs_dir[("logs/<br/>runtime logs")]
  node_localhost_ui(("localhost UI<br/>local web endpoint"))
  node_localhost_backend(("local backend<br/>local model API"))
end

node_start_bat -->|"launches"| node_start_js
node_start_sh -->|"launches"| node_start_js
node_bootstrap_ps1 -->|"bootstraps"| node_start_js
node_reset_scripts -->|"resets"| node_odysseus_repo
node_start_js -->|"probes"| node_system_js
node_start_js -->|"provisions"| node_downloader_js
node_start_js -->|"selects"| node_model_js
node_start_js -->|"supervises"| node_runtime_js
node_start_js -->|"seeds"| node_git_bootstrap
node_start_js -->|"initializes"| node_backend_common
node_downloader_js -->|"writes"| node_bin_dir
node_model_js -->|"reads/writes"| node_models_dir
node_git_bootstrap -->|"clones/updates"| node_odysseus_repo
node_backend_common -->|"configures"| node_llama_backend
node_backend_common -->|"configures"| node_ollama_backend
node_llama_backend -->|"serves"| node_localhost_backend
node_ollama_backend -->|"serves"| node_localhost_backend
node_runtime_js -->|"emits"| node_logs_dir
node_start_js -->|"opens"| node_localhost_ui
node_localhost_ui -->|"renders"| node_odysseus_repo
node_odysseus_repo -->|"calls"| node_localhost_backend

click node_start_bat "https://github.com/techjarves/odysseus-portable/blob/main/start.bat"
click node_start_sh "https://github.com/techjarves/odysseus-portable/blob/main/start.sh"
click node_bootstrap_ps1 "https://github.com/techjarves/odysseus-portable/blob/main/scripts/bootstrap-node.ps1"
click node_start_js "https://github.com/techjarves/odysseus-portable/blob/main/src/start.js"
click node_system_js "https://github.com/techjarves/odysseus-portable/blob/main/src/system.js"
click node_downloader_js "https://github.com/techjarves/odysseus-portable/blob/main/src/downloader.js"
click node_model_js "https://github.com/techjarves/odysseus-portable/blob/main/src/model.js"
click node_runtime_js "https://github.com/techjarves/odysseus-portable/blob/main/src/runtime.js"
click node_git_bootstrap "https://github.com/techjarves/odysseus-portable/blob/main/src/bootstrap/git.js"
click node_backend_common "https://github.com/techjarves/odysseus-portable/blob/main/src/backends/common.js"
click node_llama_backend "https://github.com/techjarves/odysseus-portable/blob/main/src/backends/llama/index.js"
click node_ollama_backend "https://github.com/techjarves/odysseus-portable/blob/main/src/backends/ollama/index.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_start_bat,node_start_sh,node_bootstrap_ps1,node_reset_scripts toneBlue
class node_start_js,node_system_js,node_downloader_js,node_model_js,node_runtime_js,node_git_bootstrap toneAmber
class node_backend_common,node_llama_backend,node_ollama_backend toneMint
class node_odysseus_repo,node_bin_dir,node_models_dir,node_logs_dir,node_localhost_ui,node_localhost_backend toneRose
```

## Components

### Launchers

OS-specific entry points and maintenance helpers.

- [start.bat](https://github.com/techjarves/odysseus-portable/blob/main/start.bat): entry script · Windows wrapper that starts the launcher. · `start.bat`
- [start.sh](https://github.com/techjarves/odysseus-portable/blob/main/start.sh): entry script · Unix shell wrapper that starts the launcher. · `start.sh`
- [bootstrap-node.ps1](https://github.com/techjarves/odysseus-portable/blob/main/scripts/bootstrap-node.ps1): bootstrap script · PowerShell bootstrapper for Windows runtime setup. · `scripts/bootstrap-node.ps1`
- **reset helpers**: maintenance scripts · Reset and recovery scripts for the portable workspace.

### Core Orchestration

Node-based startup control plane and provisioning logic.

- [start.js](https://github.com/techjarves/odysseus-portable/blob/main/src/start.js): orchestrator · Main startup sequence and service coordination. · `src/start.js`
- [system.js](https://github.com/techjarves/odysseus-portable/blob/main/src/system.js): platform probe · Detects host OS and hardware capabilities for runtime sizing and selection. · `src/system.js`
- [downloader.js](https://github.com/techjarves/odysseus-portable/blob/main/src/downloader.js): artifact fetcher · Downloads and extracts portable runtimes and other dependencies. · `src/downloader.js`
- [model.js](https://github.com/techjarves/odysseus-portable/blob/main/src/model.js): model manager · Finds, selects, and retrieves local GGUF model artifacts. · `src/model.js`
- [runtime.js](https://github.com/techjarves/odysseus-portable/blob/main/src/runtime.js): process supervisor · Starts, stops, logs, and restarts child processes. · `src/runtime.js`
- [git bootstrap](https://github.com/techjarves/odysseus-portable/blob/main/src/bootstrap/git.js): repo seeding · Initializes or updates the external Odysseus application repository. · `src/bootstrap/git.js`

### Backends

Local model-serving adapters and shared backend setup.

- [common.js](https://github.com/techjarves/odysseus-portable/blob/main/src/backends/common.js): backend setup · Shared backend initialization and self-healing setup logic. · `src/backends/common.js`
- [llama backend](https://github.com/techjarves/odysseus-portable/blob/main/src/backends/llama/index.js): llama adapter · Main llama.cpp integration for serving GGUF models locally. · `src/backends/llama/index.js`
- [ollama backend](https://github.com/techjarves/odysseus-portable/blob/main/src/backends/ollama/index.js): ollama adapter · Alternate local model-serving adapter based on Ollama. · `src/backends/ollama/index.js`

### Workspace State

Portable runtime, model, and external app boundaries managed by the launcher.

- **odysseus repo**: external web app · Separate user-facing Odysseus application cloned and run locally.
- **bin/**: portable runtimes · Downloaded local binaries and runtime payloads kept inside the project.
- **models/**: model cache · Stored GGUF model files and downloads managed by the launcher.
- **logs/**: runtime logs · Process and launch logs produced by the local environment.
- **localhost UI**: local web endpoint · Browser-opened Odysseus interface on the local machine.
- **local backend**: local model API · Private localhost inference service exposed by the selected backend.

## Connections

- start.bat → start.js: launches · Windows entry wrapper starts the Node launcher.
- start.sh → start.js: launches · Shell entry wrapper starts the Node launcher.
- bootstrap-node.ps1 → start.js: bootstraps · Windows bootstrapper prepares Node and environment for startup.
- reset helpers → odysseus repo: resets · Maintenance scripts can clear or restore the workspace.
- start.js → system.js: probes · Launcher checks hardware and platform capabilities first.
- start.js → downloader.js: provisions · Launcher fetches portable dependencies when needed.
- start.js → model.js: selects · Launcher resolves which local model to use.
- start.js → runtime.js: supervises · Launcher coordinates service process lifecycle.
- start.js → git bootstrap: seeds · Launcher prepares or updates the external app repository.
- start.js → common.js: initializes · Launcher applies shared backend setup before starting services.
- downloader.js → bin/: writes · Portable runtime binaries are stored inside the workspace.
- model.js → models/: reads/writes · Model discovery and downloads operate within the local models area.
- git bootstrap → odysseus repo: clones/updates · External Odysseus app is maintained as a separate local repo.
- common.js → llama backend: configures · Shared setup feeds the main llama backend.
- common.js → ollama backend: configures · Shared setup feeds the Ollama backend.
- llama backend → local backend: serves · Llama backend exposes the local inference API.
- ollama backend → local backend: serves · Ollama backend can expose the local inference API.
- runtime.js → logs/: emits · Process supervision writes runtime logs.
- start.js → localhost UI: opens · Launcher opens the local Odysseus web interface in the browser.
- localhost UI → odysseus repo: renders · The browser UI is provided by the external Odysseus application.
- odysseus repo → local backend: calls · The web app talks to the local model backend on localhost.