Skip to content

Strategic Development Approach

Foundation I → MVP → Foundation II → PoCs → Feature Groups. Essential infrastructure only.

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.

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: Basic abstraction layer to LLM providers via Ollama
  • Model Configuration: Basic model configuration for text-based conversations
  • Model Execution: Basic model execution for text-based conversations

WebView Avatar Integration (Required for MVP Embodiment)

  • WebView Widget: Flutter WebView setup for avatar rendering
  • JavaScript Bridge: Bidirectional communication channels
  • Three.js Foundation: Basic 3D scene setup with camera and lighting
  • Ready Player Me: Avatar loading and customization pipeline
  • TalkingHead.js: Lip-sync and facial expression integration
  • Performance Optimization: WebView memory management

Basic Resource Management (Required for LLM Operations)

  • Resource Monitor: CPU, memory, battery, and system load tracking
  • Job Scheduler: Task queue with priority scheduling for LLM operations
  • Resource Policies: Configurable limits for LLM inference
  • Background Processing: Pause/resume capabilities for non-critical tasks
  • Battery Awareness: Reduced processing on battery power
  • User Activity Detection: Idle detection for opportunistic processing

Security & Privacy (MVP Requirements)

  • Authentication: Basic user authentication system
  • Authorization: Role-based access control
  • Data Encryption: End-to-end encryption for sensitive data
  • Secure Communication: TLS for all network communication
  • Privacy Controls: Granular consent management

Foundation I Complete When

Core Functionality

  • Message bus handles 1000+ messages/second with < 100ms latency
  • Core services restart gracefully without data loss
  • Development environment setup < 5 minutes
  • All components work offline by default
  • LLM operations can run with resource monitoring

System Integration

  • Flutter app communicates with backend via REST/WebSocket
  • Avatar system renders in WebView with real-time updates
  • Message bus routes messages between all core modules
  • Resource monitor enforces CPU/memory/battery policies for LLM
  • Encrypted local storage with backup/restore
  • Cross-platform deployment (Windows/macOS/Linux)

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

Next: See MVP Roadmap (file does not exist) for companion AI features, then Foundation II for advanced infrastructure.