Application State & Local DB
Relevant source files
The following files were used as context for generating this wiki page:
The Linux Archductor application manages complex state across multiple layers, ranging from volatile runtime UI state to persistent configuration files and a local SQLite database. The system is designed to handle parallel coding agent workflows within isolated Git worktrees, requiring synchronization between the GTK frontend and the core management logic.
The architecture relies on a "Project" model where each project wraps a Git repository, containing multiple "Workspaces" that map to specific branches and worktrees. State management ensures that UI preferences, active workspace selections, and background process records are accurately maintained and reflected across different app pages.
Sources: README.md:12-25, crates/gtk-app/src/state.rs:1-20
Global Application State
The AppState struct serves as the central hub for managing the non-persistent runtime state of the GTK application. It utilizes thread-safe reference counting (Rc) and interior mutability (RefCell) to allow multiple UI components to react to state changes.
Key State Components
- Navigation State: Tracks the current active page (Dashboard, Projects, Workspace, etc.) and the selected workspace.
- UI Preferences: Manages the active tab within a workspace (e.g., Chats, Changes, Checks, Todos) and staged prompts for agents.
- Selection State: Tracks the currently active chat thread ID within a workspace session.
The diagram above illustrates the logical composition of the AppState object and the various UI segments it controls.
Sources: crates/gtk-app/src/state.rs:22-110, crates/gtk-app/src/main.rs:435-450
Local SQLite Database
Persistent state for repositories, workspaces, processes, and historical data is stored in a local SQLite database located at ~/.local/share/linux-archductor/linux-archductor.db.
Storage Modules
RepositoryStore: Manages the registration of local repositories and Git URLs.WorkspaceStore: Handles the lifecycle of Git worktrees, branch management, and workspace-specific metadata.ProcessRecord: Tracks background execution for setup scripts, run scripts, and agent sessions.
Data Schema Overview
| Entity | Description | Derived From |
|---|---|---|
Project | Registered codebase entry owning settings and workspaces. | crates/gtk-app/src/projects.rs |
Workspace | Isolated Git worktree mapping to a specific task or PR. | crates/gtk-app/src/workspace_command_center.rs |
ChatThread | Persistent record of agent sessions, including provider and status. | crates/gtk-app/src/workspace_command_center.rs |
Process | Background process metadata including PID, exit code, and log path. | crates/gtk-app/src/workspace_command_center.rs |
Sources: README.md:300-305, crates/gtk-app/src/workspace_command_center.rs:40-60
Settings & Configuration Layers
Archductor uses a layered TOML configuration system to manage repository-level behavior. This allows for team-shared defaults while permitting per-machine overrides.
Configuration Hierarchy
- Shared Settings: Located at
.archductor/settings.tomlin the repository root. This file is intended to be committed to version control. - Local Overrides: Located at
.archductor/settings.local.toml. This is for machine-specific secrets, executable paths, or per-user preferences. - Prompt Packs: File-backed prompt guidance stored in
.archductor/prompt-packs/.
The configuration is merged at runtime, with local overrides taking precedence over shared settings.
Sources: crates/core/src/settings.rs:175-210, crates/gtk-app/src/settings.rs:40-100
Workspace Runtime Reconciliation
Because background processes (like agent sessions or build scripts) can terminate outside of the app's direct control, the system implements a reconciliation loop.
- Startup Reconciliation: On app launch, the
reconcile_managed_sessions_on_startupfunction identifies stale process records and updates their status toExited. - Timer-based Refresh: A periodic GLib timeout (5 seconds) triggers a check for process state changes to ensure the UI status indicators (Running/Stopped) remain accurate.
- Spotlight Sync: Synchronizes workspace patches when the application detects file system changes via the
SpotlightFileWatcher.
Sources: crates/gtk-app/src/main.rs:650-680, crates/gtk-app/src/main.rs:750-780
Historical State & Imports
The history module provides access to both native Linux Archductor sessions and legacy data imported from the macOS Conductor database.
History Categories
- Active: Workspaces currently running processes or with open PRs.
- Backlog: Saved workspaces that are currently idle.
- Archived: Workspaces that have been explicitly archived, potentially with their worktrees removed.
The History page retrieves these records by querying the local SQLite database and merging them with the legacy SQLite database if present at the default Conductor app path.
Sources: crates/gtk-app/src/history.rs:160-200, crates/gtk-app/src/history.rs:260-300
Conclusion
The application state architecture provides a robust foundation for parallel agent workflows. By separating volatile UI state in AppState from persistent records in SQLite and layered TOML settings, Linux Archductor ensures that user preferences and long-running agent tasks are preserved across application restarts and workspace transitions.