Architecture Overview

Mia is designed as a modular daemon with pluggable AI backends, peer-to-peer connectivity, and persistent memory. Here’s how the pieces connect.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    USER INTERFACE LAYER                  │
├─────────────────────────────────────────────────────────┤
│  Mobile App (primary — React Native, Hyperswarm P2P)     │
│  CLI (mia chat, ask, commit, ...)                       │
│  P2P Sub-Agent (stdio-based IPC child process)          │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                      DAEMON CORE                        │
├─────────────────────────────────────────────────────────┤
│  Process lifecycle (PID, shutdown hooks, watchdog)       │
│  Plugin system (registry, dispatcher, middleware)        │
│  Message routing & dispatch queue                       │
│  P2P connection management                              │
│  Scheduler & memory pruning                             │
└──┬───────┬──────────┬───────────┬──────────┬────────────┘
   │       │          │           │          │
   ▼       ▼          ▼           ▼          ▼
┌──────┐┌──────┐┌──────────┐┌─────────┐┌──────────┐
│Plugin││ P2P  ││  Memory  ││ Context ││Scheduler │
│System││Netwrk││  Store   ││ Builder ││          │
├──────┤├──────┤├──────────┤├─────────┤├──────────┤
│Claude││Hyper-││ SQLite   ││Workspace││node-cron │
│Gemini││swarm ││ FTS5     ││ Scanner ││Persistent│
│Codex ││Hyper-││ BM25     ││ Git ctx ││JSON store│
│Open- ││DB    ││ LRU cache││ Token   ││Overlap   │
│Code  ││      ││          ││ budget  ││prevent   │
└──────┘└──────┘└──────────┘└─────────┘└──────────┘

Component Summary

Daemon Core

The central process that orchestrates everything. It:

• Manages the process lifecycle (PID files, graceful shutdown, watchdog timer)
• Initializes all subsystems in order (context → memory → plugins → P2P → scheduler)
• Routes messages between CLI, mobile, and plugins
• Runs the dispatch middleware chain

Plugin System

A registry of AI backends with a common interface. Each plugin can:

• Accept prompts with context
• Stream responses via NDJSON callbacks
• Maintain session state for multi-turn conversations
• Report availability and handle errors

The PluginDispatcher coordinates dispatch with a middleware chain and fallback logic.

P2P Network

Serverless peer-to-peer connectivity via Hyperswarm DHT:

• QR code pairing (seed-based topic derivation)
• Encrypted connections (no relay servers)
• Real-time message sync between daemon and mobile app
• HyperDB append-only log for reliable delivery

Memory Store

SQLite-backed persistent knowledge:

• Full-text search via FTS5 with BM25 ranking
• Automatic fact extraction from conversations
• Query result caching (LRU, 30-second TTL)
• FIFO eviction with configurable row cap

Context Builder

Token-aware context assembly:

• Workspace scanning (git state, file structure, project type)
• Ordered for prompt caching (static first, volatile last)
• Automatic truncation when token budget is exceeded
• Memory fact injection based on relevance

Scheduler

Cron-based task automation:

• Persistent task definitions (survives restarts)
• Overlap prevention (skips if previous run still active)
• Per-task timeouts
• Results synced to mobile via P2P

Data Flow

CLI Dispatch

User types command
  → CLI parses args, connects to daemon via IPC
  → Daemon routes to handler
  → ContextPreparer builds context (workspace, memory, git)
  → PluginDispatcher sends to active plugin
  → Plugin streams response back
  → TraceLogger records the dispatch
  → MemoryExtractor saves facts (async)
  → Response displayed to user

Mobile Dispatch

User sends message from phone
  → Message arrives via Hyperswarm P2P
  → swarm-message-handler parses type
  → Daemon routes to plugin dispatch
  → Plugin streams response
  → Response broadcast to all peers
  → Mobile app displays response
  → Message stored in SQLite

Key Design Decisions

Decision	Rationale
Background daemon	Persistent state, fast startup for CLI commands
Plugin architecture	Provider-agnostic, easy to add new AI backends
P2P over WebSocket	No server infrastructure, works behind NATs
SQLite over Postgres	Zero dependencies, local-first, fast enough
NDJSON streaming	Simple, parseable, works with child process stdio
Token budgeting	Cost control, prevents context window overflow
Middleware chain	Composable dispatch pipeline (trace, verify, extract)