flynn/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2025-02-09

Pattern Overview

Overall: Multi-channel AI agent daemon with layered pipeline architecture

Key Characteristics:

• Message pipeline: Channel Adapter → ChannelRegistry → MessageRouter → AgentOrchestrator → NativeAgent → ModelClient
• Registry/factory pattern for extensible channels, tools, models, and agent configs
• Dependency injection via constructor config objects (no DI container)
• YAML + Zod config-driven feature toggling — most subsystems are optional and activated by config
• Lifecycle-managed daemon with ordered shutdown handlers (LIFO)
• SQLite for session persistence, filesystem for memory persistence, SQLite for vector embeddings

Layers

CLI Layer:

• Purpose: Parse commands, load config, bootstrap daemon or TUI
• Location: src/cli/
• Contains: Command registrations (commander.js), config loading, TUI entry
• Depends on: Config, Daemon
• Used by: End user via flynn binary
• Entry: src/cli/index.ts → registers commands: start, tui, send, sessions, doctor, config, completion

Config Layer:

• Purpose: Load YAML config, validate with Zod, expand ${ENV_VAR} references
• Location: src/config/
• Contains: Zod schema definitions (schema.ts), YAML loader with env expansion (loader.ts)
• Depends on: zod, yaml
• Used by: All layers — the Config type flows through the entire system
• Key file: src/config/schema.ts — single source of truth for all configuration types (409 lines)

Channel Layer:

• Purpose: Uniform messaging abstraction across platforms
• Location: src/channels/
• Contains: ChannelAdapter interface, ChannelRegistry, platform adapters
• Depends on: Platform SDKs (grammy, discord.js, @slack/bolt, whatsapp-web.js)
• Used by: Daemon (message routing), Automation (cron/webhook output)
• Interface: ChannelAdapter with connect(), disconnect(), send(), onMessage()
• Adapters: src/channels/telegram/adapter.ts, src/channels/discord/adapter.ts, src/channels/slack/adapter.ts, src/channels/whatsapp/adapter.ts, src/channels/webchat/adapter.ts

Agent Layer (Backend):

• Purpose: Core AI agent loop — process messages, execute tools, manage conversation
• Location: src/backends/native/
• Contains: NativeAgent (tool loop), AgentOrchestrator (delegation, compaction, memory)
• Depends on: Models, Tools, Session, Context, Memory
• Used by: Daemon (via message router), Gateway (via SessionBridge)
• Key abstraction: NativeAgent runs the tool loop; AgentOrchestrator wraps it with orchestration features

Model Layer:

• Purpose: Unified interface to LLM providers with tier-based routing and fallback
• Location: src/models/
• Contains: ModelClient interface, provider implementations, ModelRouter, retry logic, cost estimation
• Depends on: Provider SDKs (@anthropic-ai/sdk, openai, @google/generative-ai, ollama, @aws-sdk/client-bedrock-runtime)
• Used by: Agent layer, Gateway SessionBridge
• Providers: anthropic.ts, openai.ts, gemini.ts, bedrock.ts, github.ts, local/ollama.ts, local/llamacpp.ts

Tool Layer:

• Purpose: Tool registry, execution with policy enforcement and hook checks
• Location: src/tools/
• Contains: ToolRegistry, ToolExecutor, ToolPolicy, builtin tool implementations
• Depends on: Hooks (confirmation), Memory, Process/Browser managers
• Used by: Agent layer (tool loop), Gateway (tool execution)
• Three tool patterns:
  • Static: export const fooTool: Tool (e.g., src/tools/builtin/shell.ts)
  • Factory: export function createFooTool(dep): Tool (e.g., src/tools/builtin/media-send.ts)
  • Multi-factory: export function createFooTools(dep): Tool[] (e.g., src/tools/builtin/process/index.ts)

Session Layer:

• Purpose: Persistent conversation history per channel+sender pair
• Location: src/session/
• Contains: SessionStore (SQLite), SessionManager (in-memory cache + store), ManagedSession
• Depends on: better-sqlite3
• Used by: Agent layer, Gateway SessionBridge

Memory Layer:

• Purpose: Persistent knowledge across sessions — namespace-based files + hybrid vector search
• Location: src/memory/
• Contains: MemoryStore (file-based), VectorStore (SQLite-backed embeddings), HybridSearch, embedding providers, text chunker
• Depends on: Embedding providers (OpenAI, Gemini, Ollama, llama.cpp, Voyage)
• Used by: Agent layer (memory injection into system prompt), Tools (memory.read/write/search)

Context Layer:

• Purpose: Token estimation and conversation compaction
• Location: src/context/
• Contains: Token estimator (tokens.ts), compaction logic (compaction.ts)
• Depends on: Agent layer (delegation for compaction), Memory (extraction)
• Used by: AgentOrchestrator (automatic compaction before each message)

Gateway Layer:

• Purpose: WebSocket JSON-RPC server + HTTP static file server + vanilla JS dashboard
• Location: src/gateway/
• Contains: GatewayServer, Router, SessionBridge, LaneQueue, auth, protocol, static serving, Tailscale Serve
• Depends on: ws, Session, Agent, Tools
• Used by: WebChat adapter, TUI (connects as WS client), external dashboard clients
• Protocol: JSON-RPC 2.0 over WebSocket

Hooks Layer:

• Purpose: Pattern-based tool confirmation engine
• Location: src/hooks/
• Contains: HookEngine with glob-pattern matching for confirm/log/silent actions
• Depends on: Nothing (pure logic)
• Used by: ToolExecutor (checks before execution)

Prompt Layer:

• Purpose: Assemble system prompt from template files (SOUL.md, AGENTS.md, etc.)
• Location: src/prompt/
• Contains: Template search and assembly logic
• Depends on: Filesystem (searches multiple directories)
• Used by: Daemon (system prompt construction at startup)

MCP Layer:

• Purpose: Model Context Protocol server management — bridge external MCP tools into the tool registry
• Location: src/mcp/
• Contains: McpClient, McpManager, tool bridging (bridge.ts)
• Depends on: @modelcontextprotocol/sdk
• Used by: Daemon (starts MCP servers, registers bridged tools)

Skills Layer:

• Purpose: Pluggable skill system — bundled, managed (installed), and workspace skills
• Location: src/skills/
• Contains: SkillRegistry, SkillInstaller, skill loader
• Depends on: Filesystem
• Used by: Daemon (loads skills, injects into system prompt)

Agents Config Layer:

• Purpose: Named agent configurations with per-agent overrides (model tier, tools, sandbox)
• Location: src/agents/
• Contains: AgentConfigRegistry, AgentRouter (channel+sender → agent config resolution)
• Depends on: Config
• Used by: Daemon message router (selects agent config per session)

Automation Layer:

• Purpose: Scheduled tasks, webhooks, heartbeat monitoring, Gmail watching
• Location: src/automation/
• Contains: CronScheduler, WebhookHandler, HeartbeatMonitor, GmailWatcher
• Depends on: croner, googleapis, Channels
• Used by: Daemon (registers as channel adapters or standalone monitors)

Sandbox Layer:

• Purpose: Docker container isolation for tool execution
• Location: src/sandbox/
• Contains: DockerSandbox, SandboxManager, sandboxed shell/process tools
• Depends on: Docker CLI
• Used by: Daemon message router (replaces shell/process tools with sandboxed variants)

Frontend Layer (Legacy):

• Purpose: Direct Telegram bot integration and TUI
• Location: src/frontends/
• Contains: Telegram bot handlers with confirmation UI, TUI (minimal readline + fullscreen React/Ink)
• Depends on: grammy (Telegram), ink/react (TUI)
• Used by: CLI commands (start uses Telegram frontend, tui uses TUI)

Data Flow

Inbound Message Processing (Channel → Response):

1. Platform SDK receives message → Channel adapter normalizes to InboundMessage
2. Adapter calls onMessage() callback → ChannelRegistry.handleInbound() routes to MessageHandler
3. createMessageRouter() resolves agent config via AgentRouter.resolve(channel, senderId)
4. getOrCreateAgent() creates/retrieves AgentOrchestrator for the session (cached by channel:sender:agentConfig)
5. Audio attachments transcribed if present
6. orchestrator.process() → injects memory context → checks compaction → delegates to NativeAgent.process()
7. NativeAgent.toolLoop() → sends to ModelRouter.chat() → model returns response or tool calls
8. If tool calls: ToolExecutor.execute() → policy check → hook check → tool execution → loop back to model
9. Final text response returned → reply function sends via adapter → adapter.send() → platform SDK

Gateway WebSocket Flow:

1. Client connects via WebSocket → auth check → SessionBridge.connect() → NativeAgent created
2. Client sends JSON-RPC message → GatewayServer.handleMessage() → Router.dispatch() → handler
3. agent.send handler → LaneQueue serializes requests → SessionBridge processes via NativeAgent
4. Streaming events sent back via WebSocket as JSON-RPC notifications
5. HTTP requests serve static dashboard UI or webhook endpoints

Model Routing with Fallback:

1. ModelRouter.chat(request, tier) → tries primary client for requested tier
2. If retry config enabled: withRetry() wraps call with exponential backoff
3. On failure → try tier-specific fallbacks (e.g., Anthropic → GitHub Models same model)
4. On failure → try global fallback chain (typically local model)
5. All failures → throw aggregated error

Compaction Flow:

1. Before each process(), AgentOrchestrator.compactIfNeeded() checks token count vs threshold
2. If threshold exceeded → compactHistory() splits messages into compactable + recent (keep N turns)
3. Delegates summarization to fast tier via orchestrator.delegate()
4. Optionally extracts memory facts via separate delegation call
5. Replaces session history with [summary_message, ...recent_messages]

State Management:

• Session history: SQLite (~/.local/share/flynn/sessions.db) + in-memory cache in SessionManager
• Memory: Namespace-based markdown files in ~/.local/share/flynn/memory/
• Vectors: SQLite (~/.local/share/flynn/vectors.db) for embeddings
• Config: YAML file at ~/.config/flynn/config.yaml (read once at startup)

Key Abstractions

ModelClient:

• Purpose: Uniform interface to any LLM provider
• Interface: chat(request: ChatRequest): Promise<ChatResponse> + optional chatStream()
• Implementations: src/models/anthropic.ts, src/models/openai.ts, src/models/gemini.ts, src/models/bedrock.ts, src/models/github.ts, src/models/local/ollama.ts, src/models/local/llamacpp.ts
• Pattern: Each provider wraps its SDK and normalizes to ChatResponse

ModelRouter:

• Purpose: Tier-based model selection with cascading fallback
• Location: src/models/router.ts
• Tiers: fast, default, complex, local — each maps to a ModelClient
• Implements ModelClient interface itself, so consumers don't need to know about tiers

ChannelAdapter:

• Purpose: Normalize platform-specific messaging into a common interface
• Interface: connect(), disconnect(), send(peerId, msg), onMessage(handler)
• Location: src/channels/types.ts
• Pattern: Each adapter wraps a platform SDK, handles auth/filtering, emits InboundMessage

Tool:

• Purpose: Executable capability exposed to the AI model
• Interface: { name, description, inputSchema, execute(args): Promise<ToolResult> }
• Location: src/tools/types.ts
• Registration: tool file → src/tools/builtin/index.ts → src/tools/index.ts → src/daemon/index.ts

Session:

• Purpose: Conversation state (message history) for a channel+sender pair
• Interface: addMessage(), getHistory(), clear(), replaceHistory()
• Location: src/session/manager.ts
• ID format: channel:senderId (e.g., telegram:123456)

AgentOrchestrator:

• Purpose: Wraps NativeAgent with delegation, compaction, memory, usage tracking
• Location: src/backends/native/orchestrator.ts
• Key method: delegate(SubAgentRequest) — stateless single-turn call to any tier
• Delegation tasks: compaction, memory extraction, classification, tool summarisation, complex reasoning

DaemonContext:

• Purpose: Holds all initialized subsystems returned by startDaemon()
• Location: src/daemon/index.ts
• Contains: config, lifecycle, session/model/tool/channel/gateway/mcp/skill/agent registries

Entry Points

CLI Binary (flynn):

• Location: src/cli/index.ts
• Triggers: flynn start, flynn tui, flynn send, flynn sessions, flynn doctor, flynn config
• Responsibilities: Parse args, load config, bootstrap subsystems

Daemon Start:

• Location: src/daemon/index.ts → startDaemon(config)
• Triggers: flynn start CLI command
• Responsibilities: Initialize all subsystems in order, wire dependencies, start channel adapters and gateway

Gateway Server:

• Location: src/gateway/server.ts
• Triggers: HTTP/WS connections on configured port (default 18800)
• Responsibilities: JSON-RPC routing, WebSocket session management, static UI serving, webhook HTTP endpoints

TUI:

• Location: src/frontends/tui/minimal.ts (readline) and src/frontends/tui/fullscreen.ts (React/Ink)
• Triggers: flynn tui or flynn tui --fullscreen
• Responsibilities: Local interactive chat interface connecting to gateway via WebSocket

Error Handling

Strategy: Catch-and-convert with descriptive context. No global error handler.

Patterns:

• Model layer: Retry with exponential backoff → tier fallback → global fallback → throw aggregated error
• Tool execution: Promise.race timeout → catch → return ToolResult { success: false, error: message }
• Channel adapters: Promise.allSettled for start/stop — log per-adapter errors, don't crash
• Daemon: Lifecycle LIFO shutdown handlers — each wrapped in try/catch
• Config: Zod validation throws with structured error messages on invalid config
• Gateway: JSON-RPC error codes (ParseError, MethodNotFound, InternalError)

Cross-Cutting Concerns

Logging: console.log/console.error/console.warn/console.debug throughout. No structured logging framework. Debug-level messages for model fallback decisions.

Validation: Zod for config validation (src/config/schema.ts). Tool args validated by model-provided schema. No runtime validation on tool args beyond what the tool itself checks.

Authentication: Multi-layer:

• Gateway: Bearer token auth + optional Tailscale identity header (src/gateway/auth.ts)
• Telegram: allowed_chat_ids whitelist
• Discord: allowed_guild_ids + allowed_channel_ids whitelists
• Slack: allowed_channel_ids whitelist + signing secret
• WhatsApp: allowed_numbers + allowed_group_ids whitelists
• Webhooks: HMAC signature verification (per-webhook secret)
• Pairing: DM pairing codes for unknown senders (src/channels/pairing.ts)

Tool Policy: Profile-based filtering (minimal/messaging/coding/full) + glob-pattern allow/deny lists + per-agent/per-provider overrides (src/tools/policy.ts).

Configuration: Single YAML file with ${ENV_VAR} expansion, validated by comprehensive Zod schema. Every subsystem is feature-toggled via config. Default config path: ~/.config/flynn/config.yaml.

---

Architecture analysis: 2025-02-09