Technical Specification: Local Desktop Production Deployment

[marcvergees]

Summary

The goal is to provide a complete, offline-first experience by bundling the frontend UI, Python FastAPI backend, embedded databases (PostgreSQL & Redis), and local LLM runtime (Ollama with Qwen) into a single desktop installer managed by an Electron/Tauri shell.

---

1. System Architecture Overview

The desktop app shell serves as the primary process manager, booting local infrastructure sequentially on launch and communicating via local loopback (127.0.0.1).

 ┌─────────────────────────────────────────────────────────────────┐
 │                         HOST OS RUNTIME                         │
 │                                                                 │
 │  ┌───────────────────────────────────────────────────────────┐  │
 │  │             Desktop Shell (Electron / Tauri)              │  │
 │  │  • Renders React Frontend (Local static assets)           │  │
 │  │  • Spawns & monitors local background subprocesses         │  │
 │  └─────────────────────────────┬─────────────────────────────┘  │
 │                                │ IPC / HTTP                     │
 │  ┌─────────────────────────────▼─────────────────────────────┐  │
 │  │           FastAPI Server (PyInstaller Executable)         │  │
 │  │  • Runs on http://127.0.0.1:8000                           │  │
 │  │  • Handles REST, WebSockets, background tasks             │  │
 │  └───────┬─────────────────────┬─────────────────────┬───────┘  │
 │          │ Local Socket        │ Local Socket        │ HTTP     │
 │          ▼                     ▼                     ▼          │
 │  ┌───────────────┐     ┌───────────────┐     ┌───────────────┐  │
 │  │  PostgreSQL   │     │ Redis Server  │     │ Ollama Engine │  │
 │  │ (Embedded Bin)│     │ (Embedded Bin)│     │ (Host Native) │  │
 │  └───────┬───────┘     └───────┬───────┘     └───────┬───────┘  │
 │          │                     │                     │          │
 └──────────┼─────────────────────┼─────────────────────┼──────────┘
            │ Local Storage       │ Local Storage       │ Weights
 ┌──────────▼─────────────────────▼─────────────────────▼──────────┐
 │                         NVMe DISK PATHS                         │
 │  • Windows: %APPDATA%/YourApp/data/                             │
 │  • macOS:   ~/Library/Application Support/YourApp/data/       │
 │  • Linux:   ~/.config/yourapp/data/                              │
 └─────────────────────────────────────────────────────────────────┘

---

2. Component Packaging Matrix

Component	Packaging / Distribution Strategy	Windows Asset	macOS Asset	Linux Asset
Frontend UI	Bundled static React build inside desktop application shell	.asar bundle	.app/Contents/Resources	app.asar
FastAPI Backend	Compiled single-file executable using PyInstaller	backend.exe	backend (Mach-O)	backend (ELF)
PostgreSQL	Portable PostgreSQL binaries initialized via initdb	bin/postgres.exe	bin/postgres	bin/postgres
Redis	Portable Redis (Linux/macOS) / Native Windows Redis build	redis-server.exe	bin/redis-server	bin/redis-server
Ollama & Qwen	Automated silent download via installer or background process	OllamaSetup.exe	ollama-darwin	install.sh

---

3. Runtime Lifecycle & Subprocess Orchestration

Boot Sequence

[User Launches App]
        │
        ├── 1. Check/Start Ollama Background Service (Port 11434)
        ├── 2. Spawn Embedded PostgreSQL (Port 5432, data dir checked)
        ├── 3. Spawn Embedded Redis (Port 6379)
        ├── 4. Launch FastAPI Executable (Port 8000)
        └── 5. Load React Frontend UI -> Connect to http://127.0.0.1:8000

Subprocess Management Snippet (main.js)

const { app, BrowserWindow } = require('electron');
const { spawn, execSync } = require('child_process');
const path = require('path');
const http = require('http');

let pyBackend, pgProcess, redisProcess;

const DATA_DIR = path.join(app.getPath('userData'), 'database_data');
const BIN_DIR = path.join(process.resourcesPath, 'bin');

function startServices() {
  // 1. Start Embedded PostgreSQL
  pgProcess = spawn(path.join(BIN_DIR, 'postgres'), [
    '-D', DATA_DIR,
    '-p', '5432',
    '-h', '127.0.0.1'
  ]);

  // 2. Start Embedded Redis
  redisProcess = spawn(path.join(BIN_DIR, 'redis-server'), [
    '--port', '6379',
    '--bind', '127.0.0.1',
    '--save', '60', '1'
  ]);

  // 3. Start PyInstaller FastAPI Binary
  pyBackend = spawn(path.join(BIN_DIR, 'backend'), [], {
    env: {
      ...process.env,
      DATABASE_URL: "postgresql://app_user:localpass@127.0.0.1:5432/production_db",
      REDIS_URL: "redis://127.0.0.1:6379/0",
      OLLAMA_BASE_URL: "http://127.0.0.1:11434"
    }
  });
}

// Graceful termination on window close
app.on('will-quit', () => {
  if (pyBackend) pyBackend.kill('SIGINT');
  if (redisProcess) redisProcess.kill('SIGINT');
  if (pgProcess) {
    // Send pg_ctl stop to ensure WAL logs commit safely
    execSync(`"${path.join(BIN_DIR, 'pg_ctl')}" stop -D "${DATA_DIR}" -m fast`);
  }
});

---

4. First-Run Setup & Qwen Model Provisioning

On initial app launch, the application conducts a self-healing setup routine:

1. Database Initialization: If DATA_DIR is empty, run initdb -D <DATA_DIR> followed by Alembic migrations (alembic upgrade head).
2. Ollama Detection: Ping http://127.0.0.1:11434/api/tags. If unresponsive, execute the bundled silent installer.
3. Automated Model Pull: Request model provisioning via Ollama API:

POST http://127.0.0.1:11434/api/pull
Content-Type: application/json

{
  "name": "qwen2.5:3b"
}

Stream byte progress (completed vs total) directly into the frontend onboarding wizard.

---

5. Packaging & Installers

Windows: Inno Setup (installer.iss)

[Setup]
AppName=LocalAIApp
AppVersion=1.0.0
DefaultDirName={autopf}\LocalAIApp
DefaultGroupName=LocalAIApp
OutputDir=build
OutputBaseFilename=LocalAIApp-Setup-x64
Compression=lzma2/ultra64
SolidCompression=yes
PrivilegesRequired=lowest

[Files]
Source: "dist\win-unpacked\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs
Source: "redist\OllamaSetup.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall

[Run]
Filename: "{tmp}\OllamaSetup.exe"; Parameters: "/silent"; Flags: waituntilterminated runhidden
Filename: "{app}\LocalAIApp.exe"; Description: "Launch Application"; Flags: postinstall nowait

macOS: electron-builder

• Target Formats: Signed .dmg / .pkg
• Entitlements: Include com.apple.security.hypervisor, bypass App Sandbox for local socket binding.
• Architecture: Build separate arm64 and x64 targets or Universal 2 to maximize native execution speed.

---

6. Security & Data Integrity

1. Network Binding: Strictly bind all local sub-services (FastAPI, Postgres, Redis, Ollama) to 127.0.0.1. No interfaces exposed to LAN.
2. Data Persistence: Standard OS user data paths preserve DB and Redis states across updates.
3. Clean Shutdown: Postgres shutdown is handled using pg_ctl stop -m fast to prevent corruption of Write-Ahead Logs (WAL).

---

🗣️ Discussion & Open Questions

We would love to hear feedback from the team on these specific implementation points:

1. PostgreSQL vs. SQLite: Is embedded PostgreSQL required for our concurrency needs, or would SQLite (or DuckDB) significantly reduce setup friction and binary size?
2. Electron vs. Tauri: Tauri provides a vastly lower memory footprint and installer size, but Electron has more robust node process management out-of-the-box. Should we benchmark Tauri for MVP?
3. Port Collisions: How should we handle dynamic port allocation if standard ports (5432, 6379, 8000, 11434) are occupied on the host system?

Please share your thoughts, edge-case concerns, or suggestions below! 👇

[vharkins1]

Thanks for putting this together @marcvergees , this is exciting! Since it's pretty much the future of the project, I'd love to hear what everyone thinks.

On the questions, I'm leaning SQLite over Postgres since it's one user on one machine, and our tests already run on it. I'm also wondering if we even need Redis on desktop. Right now it's only the Celery queue, so jobs could maybe just run in process. And I'd probably stick with Electron since we're already on it. Curious if anyone sees it differently though!

A few other things that we should consider:

• Where Whisper fits in (maybe whisper.cpp or faster-whisper?)
• What hardware stations actually have, since that'll shape which model we default to i.e. if they're running windows how much RAM are we expecting. Maybe we should set a minimum requirement to run the app.

Again I'd love to hear from others on this since neither me nor marc has expertise in this area!