Skip to content

Foundation I Complete

✅ All essential infrastructure completed. System ready for MVP companion features.

Foundation I Roadmap

Build the essential system infrastructure required for MVP companion features. Focus on minimal viable infrastructure to support AI features, not comprehensive system architecture.

Status: ✅ COMPLETE - All phases finished, system operational in production.

Phase 1: Minimal Running System ✅

Basic Service Layer

  • Python Service: FastAPI-based backend service with basic project structure
  • Configuration System: Simple YAML/JSON config with environment variables
  • Logging Framework: Basic structured logging (console + file)
  • Health Monitoring: Simple health check endpoint
  • API Gateway: Basic REST endpoints for frontend communication

Basic Flutter Foundation

  • Project Structure: Standard Flutter project with basic folder organization
  • State Management: Simple Provider setup for app-wide state
  • Navigation: Basic navigation (can upgrade to Go Router later)
  • Theme System: Basic Material 3 theme with dark/light mode
  • API Client: Simple HTTP client with error handling

Minimal Message Bus

  • ZeroMQ Setup: Core pub/sub message bus implementation
  • Basic Topics: Essential topics (system., conversation., ui.*)
  • Message Envelope: Protocol Buffer message format
  • Message Routing: Basic topic-based routing

Basic Data Layer

  • libSQL Setup: Modern SQLite fork for local database (encryption can come later)
  • Basic Schema: Minimal tables for system state and config
  • Migration System: Simple schema versioning

Basic Security Layer

  • Master Password Setup: Require user to set a master password on first run. Never store the password—use it transiently for key derivation only. Derived keys stored securely for automatic service authentication.
  • Unified Key Management: Implement AICOKeyManager class supporting three scenarios: initial setup (interactive), user authentication (interactive), and service startup (automatic). Uses Argon2id-based key derivation from user master password with platform-native secure storage.
  • Persistent Service Authentication: Backend services can restart automatically without user password re-entry. Master key retrieved from secure storage (macOS Keychain, Windows Credential Manager, Linux Secret Service) on service startup, enabling zero-effort security for non-technical users.
  • Database Encryption Setup: Implement application-level encryption using database-native features (SQLCipher for libSQL, DuckDB encryption, LMDB EncryptedEnv). All data at rest is encrypted by default with optimal performance.
  • File Encryption Wrapper: Create EncryptedFile wrapper class using AES-256-GCM for files without native encryption support (configs, logs, ChromaDB files). Drop-in replacement for Python's open() function.
  • Database Key Derivation: Extend AICOKeyManager with derive_database_key() and derive_file_encryption_key() methods for purpose-specific key generation from master key.
  • Access Control Skeleton: Add a basic access control mechanism (deny by default, allow for core system processes only). All access is explicit, with a foundation for future ABAC/RBAC policies.

Phase 2: Core Infrastructure ✅

Enhanced Message Bus

  • Basic Topic Expansion: Add topics as AI modules are developed (start minimal)

Task Scheduler Component

  • Background Scheduler: Implement task scheduler for zero-maintenance operations (log cleanup, key rotation, health checks)
  • Cron-like Scheduling: Support for periodic tasks with configurable intervals
  • Task Registry: Plugin system for registering scheduled tasks from different subsystems
  • Failure Recovery: Automatic retry logic and error handling for scheduled tasks
  • Performance: Optimize for 1000+ messages/second with <100ms latency

Service Layer Enhancement

  • Service Management: Windows Service / Linux daemon / macOS LaunchAgent
  • Graceful Shutdown: Clean service restart without data loss
  • WebSocket Support: Real-time bidirectional communication

Data Layer Enhancement

  • libSQL Encryption: Enable built-in database encryption
  • Basic Schema: Minimal schema for MVP AI features (expand incrementally)

Flutter Enhancement

  • WebSocket Client: Real-time communication with backend
  • Request/Response Models: Typed data models for API communication (MVP-needed)
  • Error Handling: Standardized error handling and user feedback (MVP-needed)

Phase 3: MVP-Critical Infrastructure ✅

Basic Model Service (Required for text-based conversations) ✅

  • Model Service: ZeroMQ-based modelservice with Ollama integration
  • Model Configuration: Qwen3 Abliterated 8B with custom character personalities (Modelfiles)
  • Model Execution: Streaming completions with WebSocket support
  • Transformers Integration: GLiNER (NER), sentence-transformers (embeddings), BERT/RoBERTa (sentiment)
  • Auto-Management: Automatic Ollama binary installation and model pulling
  • Resource Management: Ollama 0.12+ parallel processing (4 concurrent, 2 max loaded)

WebView Avatar Integration (Ready for MVP Integration)

  • InAppWebView Package: flutter_inappwebview with localhost server support
  • InAppLocalhostServer: Built-in HTTP server for ES6 module support
  • JavaScript Bridge: Bidirectional communication (evaluateJavascript + handlers)
  • Three.js Foundation: WebGL rendering with GLTFLoader ready
  • Ready Player Me: Avatar model integration pattern defined
  • Animation System: Separate GLB files with AnimationMixer
  • TalkingHead.js: Integration pattern defined (Phase 2)
  • Active Integration: Not yet connected to live conversations (MVP task)

Basic Resource Management (Required for LLM Operations) ✅

  • Resource Monitor: CPU, memory tracking implemented in task scheduler
  • Job Scheduler: Cron-based task scheduler with resource awareness
  • Resource Policies: Configurable limits via core.yaml (memory_threshold_percent: 85)
  • Background Processing: Task scheduler with adaptive execution
  • Ollama Resource Management: Auto-unload after 30 minutes, max 2 concurrent models
  • Battery Awareness: Not yet implemented (future enhancement)
  • User Activity Detection: Not yet implemented (future enhancement)

Security & Privacy (MVP Requirements) ✅

  • Authentication: JWT-based authentication with 24-hour expiry
  • Authorization: Service-to-service authentication via CurveZMQ
  • Data Encryption: SQLCipher (AES-256-GCM) for all databases
  • Secure Communication: CurveZMQ encryption for all message bus traffic
  • Key Management: Argon2id + PBKDF2 with platform keychain integration
  • Privacy Controls: Granular consent management (future enhancement)

Foundation I Completion Status ✅

Core Functionality ✅

  • Message bus handles high-frequency messages with CurveZMQ encryption
  • Core services restart gracefully without data loss
  • Development environment setup via UV workspace (< 5 minutes)
  • All components work offline by default
  • LLM operations run with resource monitoring and auto-management

System Integration ✅

  • Flutter app communicates with backend via REST/WebSocket with streaming
  • Avatar system architecture ready (integration pending in MVP)
  • Message bus routes messages between all core modules with CurveZMQ
  • Resource monitor enforces CPU/memory policies for LLM (Ollama 0.12+)
  • Encrypted local storage (SQLCipher for all databases)
  • Cross-platform deployment (Windows/macOS/Linux) with production CLI v1.1.0
  • Backup/restore (future enhancement)

Architecture Compliance

  • Message-Driven: All module communication via ZeroMQ pub/sub
  • Modular Design: Independent modules with clear boundaries
  • Loose Coupling: Modules only depend on message contracts
  • Local-First: All core functionality works offline
  • Privacy-First: Encryption and consent management operational
  • Agency-Ready: Infrastructure supports autonomous behavior

Status: ✅ FOUNDATION I COMPLETE

Next: See MVP Roadmap for companion AI features (in progress), then Foundation II for advanced infrastructure.