TrajectoryOS Desktop Architecture

TrajectoryOS Desktop Architecture

System Overview

TrajectoryOS Desktop is a Tauri-based application that serves as the unified control center for personal trajectory management. The application combines life state physics modeling, skill tracking with decay algorithms, voice capture integration, and text-to-speech capabilities into a cohesive desktop experience. The system operates on a local-first architecture where all data remains on the user's machine, synchronized through SQLite databases and connected via the Model Context Protocol for external tool integration.

The application is built using Rust for the backend runtime and React with TypeScript for the frontend interface. Tauri provides the bridge between these two worlds, exposing Rust functions as invokable commands that the frontend can call asynchronously. This architecture enables native performance for compute-intensive operations like physics calculations while maintaining the flexibility of a modern web-based user interface.

The Life State Physics Engine

At the core of TrajectoryOS lies a physics-based model of personal progress. The system conceptualizes an individual's life trajectory as a particle moving through a gravitational field, where escape velocity represents the threshold needed to break free from stagnation and achieve meaningful progress. The escape index quantifies how close one is to achieving this velocity, computed from three primary forces.

Thrust represents the positive momentum generated through deliberate action, skill development, and goal achievement. The system calculates thrust by aggregating contributions from active skills, completed milestones, and positive life events. Each skill contributes thrust proportional to its level multiplied by an alignment factor that measures how well the skill serves the user's declared objectives.

Gravity embodies the resistive forces that impede progress. This includes skill decay over time, unresolved blockers, missed deadlines, and the accumulated weight of incomplete goals. The gravity calculation considers both the magnitude of these impediments and their temporal proximity, with recent negative events contributing more strongly than distant ones.

Mass represents the accumulated complexity and commitments that require energy to move. Active projects, pending goals, and ongoing learning paths all contribute to mass. While mass is not inherently negative, higher mass requires proportionally more thrust to achieve the same acceleration toward escape velocity.

The escape index emerges from the ratio of thrust to the product of gravity and mass, normalized to produce a value between zero and one hundred. Values above fifty indicate net positive trajectory, while values below fifty suggest the need for intervention. The system records escape index history at regular intervals, enabling trend analysis and the identification of patterns that correlate with periods of high or low momentum.

Skill Management and Decay

The skill system implements a sophisticated model of competency that acknowledges the impermanent nature of knowledge. Each skill exists within a multi-dimensional space defined by its category, current level, target level, and relationships to other skills. The system supports skill hierarchies where prerequisite relationships define learning dependencies and synergy relationships identify skills that reinforce each other when developed together.

Skill decay operates according to configurable parameters that model the natural forgetting curve. Each skill has a decay rate that determines how quickly proficiency erodes without practice, a decay threshold that sets the minimum level below which decay is considered critical, and a grace period during which recent practice provides protection against decay. The decay calculation considers the time elapsed since last practice, applies the decay rate exponentially, and generates alerts when skills approach or cross their threshold levels.

The practice logging system records each instance of skill engagement, capturing the duration, intensity, and context of the practice session. This data feeds into multiple calculations. It resets the decay timer, contributes evidence toward competency assessment, and generates the practice streak metrics that help maintain motivation through visible consistency tracking.

Competency levels follow a defined framework that maps numeric skill levels to qualitative descriptions. The framework defines levels from novice through expert, each with specific requirements for demonstrated evidence and assessment completion. The system tracks evidence items such as completed projects, certifications, and peer reviews that support claims of competency at each level. Assessment records capture both self-assessments and external validations, building a comprehensive picture of verified skill levels.

The skill graph visualization presents the network of skill relationships, showing prerequisites as directed edges and synergies as bidirectional connections. This graph enables gap analysis for learning paths, identifying which skills must be developed to unlock desired capabilities and which existing skills will accelerate the acquisition of new ones.

Voice Capture Integration

The voice capture system bridges the Speak voice recording application with TrajectoryOS, creating a unified view of voice-captured thoughts organized by the context in which they were recorded. This integration operates through a multi-layer architecture that preserves the independence of each system while enabling rich data sharing.

The Speak system captures voice recordings through a command-line interface, transcribes them using OpenAI's Whisper model, and stores the results in a local SQLite database. The context manager component, active during each recording session, captures environmental metadata including the current working directory, active git repository and branch, terminal application, and timestamp. This context travels with the transcript, enabling later organization and search based on where and when the thought was captured.

The SpeakBridgeService running within the TrajectoryOS backend periodically synchronizes data from Speak's database into TrajectoryOS's Prisma-managed schema. During synchronization, the service reads new entries from Speak, transforms them into the VoiceCapture model format, builds the VoiceCaptureDirectory hierarchy based on recorded paths, and computes topological coordinates that enable spatial querying of captures based on their conceptual relationships.

The directory tree provides hierarchical navigation through captures organized by their originating location. This proves particularly valuable for developers who capture thoughts while working across multiple projects, as each project's captures naturally group together. The tree supports expansion and collapse, capture counts at each level, and filtering to show only directories with recent activity.

The capture detail view presents the full transcript alongside its metadata, linked entities, and computed coordinates. Users can link captures to life events, skills, or projects, creating bidirectional relationships that enrich both the capture and the linked entity. The IRCP coordinate system positions each capture in a five-dimensional space where x represents the conceptual domain, y represents the emotional valence, z represents the abstraction level, t represents the temporal position, and n represents the narrative arc position.

Model Context Protocol Integration

The MCP integration enables TrajectoryOS to communicate with external tools through a standardized protocol. The implementation centers on the McpClient, a Rust structure that manages subprocess lifecycle and JSON-RPC communication with MCP-compliant servers.

When the application needs to invoke an MCP tool, it first ensures the server process is running. If not, the client spawns the server as a subprocess with stdin and stdout connected for bidirectional communication. The client then constructs a JSON-RPC request containing the method name and parameters, serializes it, and writes it to the server's stdin followed by a newline delimiter. The server processes the request and writes its response to stdout, which the client reads, parses, and returns to the caller.

The primary MCP integration connects to the Speak MCP server, which exposes text-to-speech capabilities. The speak_text command accepts text content along with optional voice and speed parameters, sends them to the MCP server, which in turn calls the OpenAI TTS API to generate audio that plays through the system speakers. Convenience commands speak_fast and speak_slow provide preset speed configurations for common use cases.

The TypeScript hooks layer provides React-friendly access to MCP functionality. The useMCPTools hook exposes server lifecycle management including start, stop, and status checking. The useSpeak hook wraps the TTS commands with state management for loading indicators and error handling. The useReflectionSpeak hook specializes in reading daily reflections aloud, composing a natural narrative from morning intentions, gratitude items, wins, and evening reflections.

Database Architecture

The application maintains its state in a SQLite database located in the user's application data directory. The database module provides a structured interface for all data operations, organized into logical domains that mirror the application's feature areas.

The life state table stores the current values of all physics model inputs including thrust components, gravity factors, mass elements, and the computed escape index. Historical snapshots of the escape index enable trend analysis over time, stored with timestamps that allow querying by date range or computing moving averages.

The skills domain encompasses multiple related tables. The primary skills table stores core skill attributes. The skill_relationships table captures prerequisite and synergy connections. The skill_targets table defines learning goals with target levels and deadlines. The skill_practice_log records individual practice sessions. The skill_evidence table tracks demonstrated competencies. The skill_assessments table maintains assessment history. The skill_decay_config table stores per-skill decay parameters. The skill_decay_alerts table tracks active decay warnings.

The goals and milestones tables implement a hierarchical goal tracking system where goals contain milestones that represent discrete progress markers. Goals carry metadata including status, priority, deadline, and progress percentage. Milestones track completion state and the date achieved.

The projects table stores project definitions with links to tracked folders and associated skills. The project_skills junction table implements the many-to-many relationship between projects and skills, enabling queries that find all skills relevant to a project or all projects that utilize a given skill.

The calendar_events table provides a lightweight event tracking capability for scheduling and timeline visualization. Events carry title, description, start time, end time, and category, supporting both single-occurrence and recurring event patterns.

The conversations and messages tables support the interview feature where users engage in guided reflection sessions. Each conversation represents a session with a topic and creation timestamp. Messages within conversations carry role indicators distinguishing user input from system responses, building a persistent record of reflective dialogue.

The daily_reflections table captures structured daily check-ins including morning intention, evening reflection, mood and energy ratings, gratitude items, and wins. This data feeds into the physics model through its influence on thrust and gravity calculations while also providing a journaling capability for personal review.

The life_events table records significant occurrences that impact trajectory, categorized by type and tagged with impact assessments. Life events can link to voice captures, creating connections between recorded thoughts and their classification as meaningful events.

The state_transitions table implements a RAG-enhanced memory system that records changes in life state along with the context that surrounded them. This enables pattern recognition where the system can identify what conditions preceded positive or negative state changes, informing policy recommendations that suggest actions likely to improve trajectory.

Tauri Command Interface

The Rust backend exposes its functionality through Tauri commands, async functions decorated with the tauri::command attribute that become callable from the frontend. Each command receives a reference to the application state, performs its operation, and returns a result that serializes to JSON for transmission to the frontend.

Commands organize into functional groups. Life state commands include get_life_state for retrieving current physics values, update_life_state for modifying inputs, and recalculate_escape_index for triggering a fresh computation. Skill commands span the full CRUD spectrum plus specialized operations like calculate_skill_decay and get_skills_at_risk. Goal commands handle creation, updates, progress tracking, and deadline queries. Project commands manage project definitions and their skill associations.

The folder tracking commands enable the application to monitor filesystem locations for changes relevant to project activity. The scan_folder command traverses a directory tree, identifying files and computing metrics that inform project status.

Notification commands interface with the operating system's notification system, enabling the application to surface alerts even when minimized. The update_tray_icon and update_tray_tooltip commands control the system tray presence, providing at-a-glance status information.

The MCP commands form their own group, handling server lifecycle and tool invocation. These commands maintain the McpState which wraps the McpClient in a mutex for thread-safe access across async command invocations.

Frontend Architecture

The React frontend implements a tab-based navigation structure where each major feature area occupies its own tab within the main dashboard. State management combines React Query for server state synchronization with Zustand stores for client-side UI state.

The Tauri invoke API provides the communication channel between frontend and backend. Each Tauri command becomes callable through the invoke function, which handles serialization, IPC transmission, deserialization, and promise resolution. Custom hooks wrap these invocations with appropriate React Query configuration, providing automatic caching, background refetching, and optimistic updates where applicable.

The voice captures tab implements a three-panel layout with the directory tree on the left, the capture list in the center, and the capture detail on the right. Selection state flows from directory to capture, with the detail panel updating to show the selected capture's full information. The list implements virtualization for performance when displaying large numbers of captures.

The skills interface presents multiple views including a list view for browsing and editing skills, a graph view for visualizing relationships, and a learning paths view for tracking progress toward skill targets. The decay monitoring panel highlights skills approaching their thresholds, sorted by urgency to focus attention on the most critical maintenance needs.

The goals dashboard shows active goals with progress indicators, upcoming milestones, and deadline warnings. The physics panel displays the current escape index with a visual gauge, trend sparkline, and breakdown of contributing factors. The reflection interface provides forms for daily check-ins and displays historical reflection data with mood and energy trend charts.

System Tray Integration

The application maintains a persistent presence in the system tray, enabling quick access and ambient awareness of trajectory status. The tray menu provides shortcuts to common actions including starting an interview session, updating state, showing or hiding the main window, and quitting the application.

Tray events trigger application responses through the on_system_tray_event handler. Menu item clicks emit events to the frontend, enabling React components to respond to tray interactions. The start_interview action emits an event that the interview component listens for, opening the interview modal when triggered from the tray.

The tray icon and tooltip update dynamically to reflect application state. The escape index can display in the tooltip, providing at-a-glance trajectory status without opening the full application. Icon variations can indicate different state ranges, using color or badge overlays to communicate status visually.

Event System

The application implements an event bus for decoupled communication between components. Events carry typed payloads that describe what occurred, enabling listeners to respond appropriately without tight coupling to event sources.

The OrbitEvent enumeration defines the event vocabulary. ShellContextChanged fires when shell hooks detect a directory change, carrying the new working directory, git repository if applicable, and any project association. Project lifecycle events signal creation, updates, and deletion. Session events track Claude Code session activity for projects under development.

Event subscribers register interest in specific event types and provide callback functions that execute when matching events fire. The event bus maintains subscriber registrations and dispatches events to all interested parties. This pattern enables features like automatic project detection when the user navigates to a git repository, triggering project creation prompts or context updates without explicit user action.

Shell Hook Integration

The shell hooks extend TrajectoryOS's awareness beyond the application window into the user's terminal environment. Installation adds functions to the shell's configuration that execute on specific triggers, most notably directory changes.

The zsh integration uses chpwd_functions, an array of function names that zsh calls whenever the working directory changes. The orbit hook function detects whether the new directory is within a git repository, extracts repository and branch information if so, and exports this context to environment variables. It also writes the context to a JSON file that the Orbit server can read, and optionally posts to the server's shell context endpoint for real-time updates.

The bash integration uses PROMPT_COMMAND, a variable containing commands that execute before each prompt display. The hook function performs the same context detection and export logic, adapted for bash's syntax differences.

The Speak integration within shell hooks exports SPEAK_GIT_REPO and SPEAK_GIT_BRANCH environment variables that the Speak context manager reads during voice capture. This pre-caching eliminates the latency of git commands during capture, ensuring context is available instantly when the user initiates a recording.

Security Considerations

The application adheres to security practices appropriate for a local-first personal tool. All data remains on the user's machine, eliminating exposure to network-based attacks on data at rest. The SQLite database resides in the application data directory with permissions inherited from the operating system's user account protections.

API keys for external services like OpenAI store in environment variables rather than in code or configuration files, preventing accidental exposure through version control or log files. The MCP client communicates with local subprocess servers over stdio, avoiding network exposure of the JSON-RPC protocol.

The Tauri security model provides additional protections. The frontend runs in a webview with restricted capabilities, unable to access the filesystem or spawn processes directly. All such operations route through Tauri commands that the Rust backend controls, enabling validation and sanitization before action execution.

Performance Characteristics

The application optimizes for responsiveness in interactive operations while accepting longer processing times for background tasks. The Rust backend handles compute-intensive operations like physics calculations and database queries, keeping the frontend thread free for user interaction.

Database operations use prepared statements and appropriate indexing to minimize query latency. The skills query, frequently executed to populate the dashboard, benefits from indexes on category and status columns. The voice capture queries filter by directory and date range, indexed accordingly.

The frontend implements virtualization for long lists, rendering only visible items plus a small buffer. This keeps the DOM lightweight regardless of total item count, maintaining smooth scrolling even with thousands of captures or skills.

React Query's caching reduces redundant network operations, returning cached data instantly while revalidating in the background. Stale-while-revalidate patterns ensure the UI always has data to display while keeping that data fresh.

Extensibility Points

The architecture provides several extension points for future capability additions. New Tauri commands can expose additional backend functionality by adding command functions and registering them in the invoke_handler. The frontend can call these commands immediately through the invoke API.

New MCP integrations follow the pattern established by the Speak integration. Creating an MCP server that implements the protocol, adding client code to manage the subprocess, and exposing Tauri commands for the relevant tools enables any MCP-compliant tool to integrate with TrajectoryOS.

The event system supports new event types by extending the OrbitEvent enumeration and adding emission points in the relevant code paths. Subscribers can then react to these events without modifying the emitting code.

The database schema evolves through the Database implementation's initialization logic, which can add columns and tables while preserving existing data. The Prisma schema on the trajectory-core service side handles its own migrations through the standard Prisma migration workflow.

Conclusion

TrajectoryOS Desktop represents a comprehensive approach to personal trajectory management, combining physics-based modeling of progress with practical tools for skill development, goal tracking, and reflective practice. The integration of voice capture and text-to-speech capabilities adds a dimension of conversational interaction, while the shell hooks extend awareness into the development environment where much of the trajectory-defining work occurs. The local-first architecture ensures privacy and reliability, with all data remaining under the user's control on their own machine. The modular design, clear separation of concerns, and standardized integration protocols position the application for continued evolution as new capabilities and integrations emerge.