Architecture Overview
GarraIA is built as a Rust workspace with 22 crates, each responsible for a specific domain.
Workspace Structure
crates/
├── garraia-cli/ # Command-line interface
├── garraia-gateway/ # HTTP/WebSocket gateway + admin console
├── garraia-config/ # Configuration management
├── garraia-channels/ # Channel integrations
├── garraia-agents/ # LLM providers + agent runtime
├── garraia-voice/ # Voice pipeline (STT/TTS)
├── garraia-db/ # SQLite memory + vector store
├── garraia-plugins/ # WASM plugin sandbox
├── garraia-media/ # PDF/image processing
├── garraia-security/ # Credential vault + auth
├── garraia-skills/ # Skill parser + installer (instruction / hardware-adapter / hardware-preset)
├── garraia-auth/ # IdentityProvider, RBAC, Argon2id, JWT + refresh tokens
├── garraia-workspace/ # Postgres 16 + pgvector multi-tenant schema (FORCE RLS)
├── garraia-storage/ # ObjectStore trait: LocalFs + S3-compatible (tus 1.0 uploads)
├── garraia-embeddings/ # EmbeddingProvider / VectorStore traits (ADR 0018 proposed)
├── garraia-learning/ # Self-improving operations manual (ADR 0010)
├── garraia-hardware/ # Physical devices: Device trait, R0-R5 risk gate, adapters
├── garraia-telemetry/ # OpenTelemetry + Prometheus (feature-gated)
├── garraia-glob/ # Glob / ignore matching
├── garraia-desktop-core/ # Tauri-free core of the Desktop Control Center (ADR 0021)
├── garraia-desktop/ # Tauri v2 shell (tray, parrot overlay, Chat Bar) — outside CI gates
└── garraia-common/ # Shared types + errors
Runtime Flow
The agent execution follows a state machine pattern:
┌─────────────────────────────────────────────────────────────┐
│ RUNTIME STATE MACHINE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ IDLE │ ───▶ │ RUNNING │ ───▶ │ DONE │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ▲ │ │ │
│ │ ▼ │ │
│ │ ┌──────────┐ │ │
│ └────────────│ ERROR │────────────┘ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Turn Execution
Each turn follows:
- Receive - Message input from channel
- Execute - Run tools, call LLM
- Respond - Stream response back to channel
Voice Pipeline
┌─────────────────────────────────────────────────────────────┐
│ VOICE PIPELINE E2E │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ AUDIO │───▶│ STT │───▶│ LLM │───▶│ TTS │ │
│ │ INPUT │ │Whisper │ │Provider│ │Chatterb│ │
│ └────────┘ └────────┘ └────────┘ │ Hibiki │ │
│ └────────┘ │
│ │
│ STT: Whisper (local), OpenAI Whisper API │
│ TTS: Chatterbox (GPU), Hibiki (GPU), OpenAI TTS │
│ │
└─────────────────────────────────────────────────────────────┘
Multi-Agent Architecture
┌─────────────────────────────────────────────────────────────┐
│ MULTI-AGENT SYSTEM │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Agent Registry │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Agent-A │ │ Agent-B │ │ Agent-C │ │ │
│ │ │ (priority:1)│ │ (priority:2)│ │ (priority:3)│ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Priority Router │ │
│ │ - Match user message to best agent │ │
│ │ - Maintain session continuity │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ A2A Protocol │ │
│ │ - JSON-RPC 2.0 agent-to-agent communication │ │
│ │ - Task submission and status updates │ │
│ │ - Agent cards at /.well-known/agent.json │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Memory System
┌─────────────────────────────────────────────────────────────┐
│ MEMORY SYSTEM │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ memory.db (SQLite + sqlite-vec) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│ │ │ Conversations│ │ Vector Store│ │ Sessions │ │ │
│ │ └─────────────┘ └─────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ facts.json │ │
│ │ - LLM-extracted facts from conversations │ │
│ │ - With context, timestamp, and source │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Embeddings (Ollama/local) │ │
│ │ - Semantic search over facts and history │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Security Architecture
┌─────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Credential Vault (AES-256-GCM + PBKDF2-SHA256) │ │
│ │ - API keys encrypted at rest │ │
│ │ - Keys: vault > config > environment variable │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Authentication │ │
│ │ - Pairing codes for WebSocket access │ │
│ │ - Per-channel user allowlists │ │
│ │ - WebSocket API key authentication │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Input Validation │ │
│ │ - Prompt injection detection (14 patterns) │ │
│ │ - Path traversal prevention │ │
│ │ - SSRF blocking │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Rate Limiting │ │
│ │ - HTTP rate limits (configurable) │ │
│ │ - WebSocket sliding window (30 msg/min) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ WASM Sandbox │ │
│ │ - Epoch deadlines │ │
│ │ - Resource limits (memory, CPU) │ │
│ │ - Path traversal prevention after canonicalization │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Data Flow
User Message → Channel Handler → Gateway → Agent Runtime → LLM
↑ ↓
Response ← WebSocket/Channel ← Stream Response ←┘
Configuration Hot-Reload
- User edits
~/.garraia/config.yml - File watcher detects changes
- Configuration is re-parsed
- New settings applied without restart