Architecture

Overview

This project is a Personal Operating Environment implemented as a desktop application using the Tauri framework. It functions as a host-level "shell" for launching, managing, and interacting with built-in modules and external plugins. It is NOT a kernel OS — it is a portable layer that runs on top of Windows from an external SSD without installation.

Portable-First Design

• The application binary lives on the external SSD alongside the user's files.
• All data (state.sqlite database, plugins, inbox, artifacts) is stored in <drive>/.octanium/ relative to the executable.
• Drive letter changes (D: → E:) are handled automatically via volume_serial_number detection at startup.
• No writes to the host registry or C:\Users\....

Frontend (React + Vite)

• Shell UI: The overarching layout (Desktop, Taskbar, Launcher) that hosts applications.
• Window Management: Floating/draggable/resizable windows (react-rnd). Dynamic z-index and window snapping.
• State Management: Uses Zustand (src/state/store.ts) for managing shell state, active apps, and globally cached settings.
• API Layer: src/api/invoke.ts acts as the bridge between frontend React components and the Rust backend.

Backend (Rust)

Core (src/core)

• AppState — shared application state (Tauri managed state).
• AppRegistry — built-in app registry today; future portable plugin discovery should load from <drive>/.octanium/plugins/.

Commands (src/commands)

Exposes host-level operations to the frontend:

• fs — workspace-bounded filesystem interactions.
• process — execution of host binaries (Python, Node, Git) with stdout/stderr capture.
• registry — querying available applications/plugins.
• settings — retrieving and persisting user configuration.
• search — FTS5-powered file search (Phase 2).
• inbox — add files to structured Inbox (Phase 2).
• collector — Artifact Collection Mode (Phase 2).
• ghost — ghost file detection and recovery (Phase 2).

Services (src-tauri/src/services — планируются в Phase 2)

Фоновые воркеры и логика ядра (в текущей версии модуль services пуст, его наполнение запланировано в рамках Phase 2):

• indexer — параллельный сканер файлов на базе jwalk + отслеживание изменений через notify.
• searcher — SQLite FTS5-запросы с триграммным токенизатором (целевое время < 50 мс).
• inbox — структурированный импорт файлов: копирование/перемещение в inbox/YYYY/MM/DD/, автотегирование, регистрация в БД.
• collector — Artifact Collection: сбор файлов в настроенный Artifact Root и привязка к проектам.
• ghost_detector — проверка целостности при запуске + события воркера → выставляет status = 'ghost' в БД для пропавших файлов.
• tagger — эвристики автоматического тегирования (расширение, mime-тип, ключевые слова).
• hasher — вычисление SHA256 первых 64 КБ файла для стабильной идентификации при переименованиях и перемещениях.
• thumbnail — фоновая генерация миниатюр (превью) для изображений и документов.

Models (src/models)

Strongly-typed serde serializable models:

• AppManifest, Settings — existing.
• FileItem, Tag, Project, Link — File Intelligence layer (Phase 2).
• SearchFilters, FileResult, GhostReport — search and ghost recovery.

Database (src-tauri/src/core/storage.rs)

• SQLite via rusqlite. База данных настроек и состояния интерфейса: <drive>/.octanium/state.sqlite.
• Таблица kv_state хранит сериализованные в JSON настройки пользователя и состояние оконной оболочки (вкладки, координаты окон).
• Проектирование и создание базы данных index.db (с таблицами items, tags, item_tags, projects, project_items, links, items_history и FTS5-таблицей items_fts), а также папки миграций src-tauri/migrations/ запланировано во Phase 2 (File Intelligence Core).

File Organization on Disk

<workspace_root>/          ← active workspace directory (configured in settings)
  .octanium/
    state.sqlite           ← SQLite database (key-value settings, shell state)
    index.db               ← SQLite database (artifact index: items, tags, projects - Phase 2)
    volume.id              ← volume serial for drive letter change detection
    plugins/               ← dynamic plugins loaded for this workspace
      my-tool/
        manifest.json
        index.html
    thumbnails/            ← Cached 256x256 JPEGs of image files
    inbox/                 ← default inbox path
      2026/06/02/
        design-ref.png
        notes.md
    artifacts/             ← default artifact root (overridable)
      AtomX/
        design/
          code/
    backups/

Data Flow: Inbox Drop

User drags file
  → Tauri drag event
  → inbox::receive(paths, mode)
    → determine date from file.created_at
    → copy/move to inbox/YYYY/MM/DD/filename
    → hasher::hash_first_64kb(path)
    → tagger::auto_tag(extension, mime)
    → INSERT INTO items + item_tags
    → FTS5 index update
    → emit event: files_added_to_inbox
  → Frontend: show notification + open Inbox view

Data Flow: Ghost Detection

notify watcher → Remove event for path
  → ghost_detector::on_remove(path)
    → UPDATE items SET status='ghost' WHERE current_path = path
    → emit event: ghost_detected(item_id)
  → Frontend: show ghost notification with [Locate] [Remove] actions

User clicks [Locate]
  → file picker → new_path
  → ghost::relocate_item(id, new_path)
    → verify file exists
    → UPDATE items SET current_path = new_path, status = 'active'
    → FTS5 index update
    → INSERT INTO items_history (action='relocated')
    → emit event: item_relocated