Core Services

Service Overview

FileSystemService

Unified file system service managing modular vault structures (Daily and Chat modules) with platform-specific security handling.

Module Architecture

~/Parachute/              (Vault Root - user configurable)
├── Daily/               (Module folder)
│   ├── journals/        (Required subfolder)
│   ├── assets/          (Required subfolder)
│   └── reflections/     (Required subfolder)
│
└── Chat/                (Module folder)
    ├── sessions/
    ├── assets/
    ├── artifacts/
    └── contexts/

Key Methods

Platform-Specific Behavior

Temp File Retention

• Recordings: 7 days
• Playback: 24 hours
• Segments: 1 hour

SyncService

Multi-phase sync orchestration between local Daily vault and server with conflict resolution and tombstone tracking.

Sync Protocol

1. Manifest Comparison
   └── SHA-256 hashing for content change detection

2. Local vs Server Decision
   └── Push/pull/merge based on timestamps and content hashes

3. Conflict Detection
   └── Files with close timestamps (<60s) + different content

4. Tombstone Tracking
   └── .tombstones/ directory tracks deleted files

5. Version Backups
   └── .versions/ keeps last 3 versions before overwriting

Conflict Resolution Strategy

Batching Strategy

• Text files: 50 files per batch (fast, checksummed)
• Binary files: 5 files per batch (slow, base64-encoded, longer timeouts)

Key Methods

StreamingVoiceService

Real-time transcription feedback during Chat voice input with VAD-based audio chunking and streaming WAV file generation.

LocalAgreement-2 Algorithm

Rolling Buffer: 30-second max audio buffer
    │
    ▼
VAD Chunker: Detects 1s silence threshold
    │
    ▼
Transcription Queue: Only chunks with ≥1s speech
    │
    ▼
Text Stability Tracking:
    ├── Confirmed (2+ iterations)
    ├── Tentative (1 iteration)
    └── Interim (changing)

Streaming State Flow

1. startRecording() - Initialize noise filter, VAD, temp WAV, wakelock
2. _processAudioChunk() - Convert bytes to int16, apply filter, stream to disk
3. _handleChunk() (VAD callback) - Queue chunk for async transcription
4. _transcribeSegment() - Transcribe chunk, add to confirmed segments
5. stopRecording() - Flush VAD, final transcription, fallback if empty
6. getStreamingTranscript() - Join segments with fuzzy overlap removal

Model Status Tracking

notInitialized → initializing (lazy init) → ready
                                          → error

TranscriptionServiceAdapter

Platform-adaptive abstraction layer selecting optimal transcription engine per platform.

Platform Strategy

Key Features

• Lazy Initialization: Models not loaded until first transcription
• Progress Tracking: Broadcasts via transcriptionProgressStream
• Fallback Logic: FluidAudio failure falls through to Sherpa-ONNX
• Singleton Management: Sherpa-ONNX isolate reused across instances

LimaVMService

Complete lifecycle management for Parachute Computer - an isolated Lima VM running the Computer server.

Lifecycle States

notInstalled ──► notCreated ──► stopped ◄──► starting
                                    │            │
                                    ▼            ▼
                                 error      running
                                    ▲            │
                                    └── stopping ◄┘

Key Methods

Auto-Start (launchd)

• Label: io.openparachute.vm
• Path: ~/Library/LaunchAgents/io.openparachute.vm.plist
• RunAtLoad: true (starts on login)

BundledServerService

Lifecycle management for bundled server binary in desktop distributions.

Status States

notBundled ──► stopped ◄──► starting
                  │            │
                  ▼            ▼
               error       running

Cross-Platform Bundle Paths

Environment Variables

• VAULT_PATH - User's vault directory
• PORT - 3333 (configurable)
• PATH - Inherited for external tool access
• HOME - Explicit to prevent sandboxing issues

Health Monitoring

• Startup: Poll /api/health every 500ms for 30s
• Running: Check every 10s
• Max Restart Attempts: 3 (then error state)

VAD System

Voice Activity Detection for intelligent audio segmentation, ported from RichardTate.

SmartChunker

VAD-based audio segmentation preventing silent/noise-only chunks from reaching transcription.

Safety Thresholds

• Min speech duration: 1s (prevents hallucinations)
• Min chunk duration: 500ms (efficiency)
• Max chunk duration: 30s (safety limit)
• Silence threshold: 1s (configurable)

SimpleVAD

RMS energy-based voice activity detection for distinguishing speech from silence.

RMS Calculation

RMS = sqrt(sum(sample^2) / num_samples)

Threshold Tuning:
- 100.0: Default (ideal lab conditions)
- 400-800+: Real-world with background noise
- Lower = more aggressive (false positives)
- Higher = conservative (may miss quiet speech)

State Tracking

• Silence/speech durations (cumulative)
• Consecutive frame counts
• Current speaking state
• Last frame classification

Error Handling Patterns

All services follow consistent patterns:

• Try-catch blocks with descriptive debugPrint logging
• Platform-specific fallbacks (e.g., home directory detection)
• Timeouts on network operations (30-120s)
• Graceful degradation rather than exceptions

Logging Convention

debugPrint('[ClassName] message');          // Standard
debugPrint('[ClassName] Success');          // Success
debugPrint('[ClassName] Warning');          // Warning
debugPrint('[ClassName] Error reason: $e'); // Error

Resource Cleanup

• Timers always cancelled in dispose()
• Stream subscriptions unsubscribed
• File handles closed
• WakeLock explicitly disabled