odysseus/docs/discovery/domains/platform.md

Platform

Features in this document are generated from ../feature-catalog.json, the canonical inventory.

PLATFORM-001 — Application Initialization & Lifespan Management

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Orchestrates server startup, database table migration, background daemon initialization, and clean shutdown.

Evidence summary

• app.py — _lifespan — FastAPI lifespan context manager executing startup tasks.
• src/app_initializer.py — initialize_app — Initializes app directories, DB schemas, and logging.

Unknowns

• Un-handled exceptions during startup halt application launch.

PLATFORM-002 — System Health, Readiness & Version Monitoring APIs

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Exposes Liveness (/api/health), Readiness (/api/ready), App Version (/api/version), and Client Perf APIs.

Evidence summary

• app.py — readiness_check — Performs system component integrity check.
• src/readiness.py — check_readiness — Checks database, storage, and key paths for read/write access.

Unknowns

• Readiness check delays if verifying connectivity to offline remote endpoints.

PLATFORM-003 — Database Schema, Migrations & SQLite Persistence

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Defines core relational tables (users, tokens, tasks, sessions) and executes automated SQLite schema upgrades.

Evidence summary

• core/database.py — init_db — Creates ORM tables and establishes connection pool.
• scripts/update_database.py — run_migrations — Applies missing schema columns and indices.

Unknowns

• SQLite file lock contention under high concurrent write loads.

PLATFORM-004 — User Data Export & Import Backup Infrastructure

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Exports complete user workspace state (sessions, memory, skills, notes, presets) into a zip archive.

Evidence summary

• routes/backup_routes.py — setup_backup_routes — Handles workspace data export and import upload unpack.
• docs/backup-restore.md — Documentation — Backup and restore operational documentation.

Unknowns

• Corrupt archive files causing partial data restore.

PLATFORM-005 — File Cleanup & Storage Maintenance Engine

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Scans data directories for orphaned files, old uploads, temporary vision images, and frees disk space.

Evidence summary

• routes/cleanup/cleanup_routes.py — @router.get('/preview') — Previews reclaimable disk space across storage directories.
• src/cleanup_service.py — CleanupService — Executes filesystem purge of orphaned asset files.

Unknowns

• Deletes files uploaded in active sessions if retention window is set too short.

PLATFORM-006 — System Health & RAG Diagnostic Suite

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Executes real-time integrity diagnostics across ChromaDB, SearXNG, local models, and network interfaces.

Evidence summary

• routes/diagnostics_routes.py — setup_diagnostics_routes — Runs subsystem health check suite.
• src/service_health.py — collect_health_status — Inspects vector database, email, search, and local provider status.

Unknowns

• Diagnostic timeout if external search provider is unreachable.

PLATFORM-007 — Desktop CLI Utilities & Shell Integration Tools

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides command-line interface tools (odysseus, odysseus-mcp, odysseus-mail) for terminal usage.

Evidence summary

• scripts/_lib/cli.py — main — Shared CLI framework for terminal helper commands.
• scripts/odysseus — odysseus — Main terminal launcher script.

Unknowns

• Outdated CLI scripts if backend API schemas change.

PLATFORM-008 — Desktop Companion App Integration

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides API routes and pairing mechanisms for the native macOS/desktop menu bar companion app.

Evidence summary

• companion/routes.py — setup_companion_routes — Endpoints for pairing and status sync with desktop companion.
• companion/pairing.py — PairingManager — Generates and validates companion pairing codes.

Unknowns

• Pairing code expiration timing window.

PLATFORM-009 — Docker Containerization & GPU Hardware Manifests

• Domain: platform
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: pending — Requires Docker GPU pass-through and compatible host drivers.

Purpose

Provides multi-stage Dockerfile and Docker Compose manifests for CPU, NVIDIA CUDA, and AMD ROCm GPUs.

Evidence summary

• Dockerfile — multi-stage-build — Multi-stage container build environment.
• docker-compose.gpu-nvidia.yml — nvidia-gpu-manifest — NVIDIA GPU pass-through container specification.
• scripts/check-docker-gpu.sh — check-docker-gpu — Automated diagnostic test script for host NVIDIA GPU passthrough.

Unknowns

• Driver version incompatibility with host NVIDIA/AMD kernel drivers.

PLATFORM-010 — Legacy FAISS Vector Index Migration Script

• Domain: platform
• Status: legacy
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Legacy utility script to migrate older FAISS vector indices into ChromaDB.

Evidence summary

• scripts/migrate_faiss_to_chroma.py — migrate_faiss — Reads FAISS vector index files and writes to ChromaDB collection.

Unknowns

• Superseded by native ChromaDB vector index pipeline.