flynn/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2025-02-09

Directory Layout

flynn/
├── src/                       # All TypeScript source code
│   ├── agents/                # Named agent configs + routing
│   ├── auth/                  # GitHub device flow auth
│   ├── automation/            # Cron, webhooks, heartbeat, Gmail
│   ├── backends/              # AI agent implementations
│   │   └── native/            # NativeAgent + AgentOrchestrator
│   ├── channels/              # Multi-platform messaging adapters
│   │   ├── discord/           # Discord adapter
│   │   ├── slack/             # Slack adapter
│   │   ├── telegram/          # Telegram adapter
│   │   ├── webchat/           # WebChat adapter (wraps gateway)
│   │   └── whatsapp/          # WhatsApp adapter
│   ├── cli/                   # CLI commands (commander.js)
│   ├── config/                # YAML config loading + Zod schema
│   ├── context/               # Token estimation + compaction
│   ├── daemon/                # Daemon bootstrap + lifecycle
│   ├── frontends/             # UI frontends
│   │   ├── telegram/          # Telegram bot (legacy direct integration)
│   │   └── tui/               # Terminal UI (readline + React/Ink)
│   │       └── components/    # Ink React components
│   ├── gateway/               # WebSocket JSON-RPC server
│   │   ├── handlers/          # JSON-RPC method handlers
│   │   └── ui/                # Vanilla JS dashboard
│   │       ├── lib/           # Shared JS (ws-client)
│   │       └── pages/         # Page JS (chat, dashboard, sessions, settings, usage)
│   ├── hooks/                 # Tool confirmation engine
│   ├── mcp/                   # Model Context Protocol bridge
│   ├── memory/                # Persistent memory + vector search
│   ├── models/                # LLM provider clients + router
│   │   └── local/             # Ollama + llama.cpp clients
│   ├── prompt/                # System prompt template assembly
│   ├── sandbox/               # Docker sandbox for tool execution
│   ├── session/               # SQLite session persistence
│   ├── skills/                # Pluggable skill system
│   └── tools/                 # Tool registry, executor, policy
│       └── builtin/           # Built-in tool implementations
│           ├── browser/       # Puppeteer browser tools
│           └── process/       # Background process tools
├── config/                    # Example/default config files
├── docs/                      # Documentation
│   └── plans/                 # Planning docs
├── .planning/                 # GSD planning documents
│   └── codebase/              # Codebase analysis (this file)
├── AGENTS.md                  # Agent instructions for Claude Code
├── CHANGELOG.md               # Version changelog
├── CLAUDE.md                  # Claude Code shared memory
├── SOUL.md                    # Flynn's AI personality/identity
├── Dockerfile                 # Docker build config
├── docker-compose.yml         # Docker Compose config
├── package.json               # Node.js package manifest
├── tsconfig.json              # TypeScript configuration
└── pnpm-lock.yaml             # Lockfile

Directory Purposes

src/agents/:

• Purpose: Named agent configurations and routing logic
• Contains: AgentConfigRegistry (stores named configs), AgentRouter (resolves channel+sender → agent config)
• Key files: src/agents/registry.ts, src/agents/router.ts

src/auth/:

• Purpose: GitHub device flow authentication for GitHub Models provider
• Contains: OAuth device flow implementation
• Key files: src/auth/github.ts

src/automation/:

• Purpose: Scheduled jobs, incoming webhooks, health monitoring, Gmail watching
• Contains: CronScheduler (croner-based), WebhookHandler (HMAC auth), HeartbeatMonitor, GmailWatcher
• Key files: src/automation/cron.ts, src/automation/webhooks.ts, src/automation/heartbeat.ts, src/automation/gmail.ts

src/backends/native/:

• Purpose: Core AI agent implementation — message processing and tool execution loop
• Contains: NativeAgent (tool loop), AgentOrchestrator (delegation/compaction/memory wrapper), prompt templates
• Key files: src/backends/native/agent.ts, src/backends/native/orchestrator.ts, src/backends/native/prompts.ts, src/backends/native/attachments.ts

src/channels/:

• Purpose: Platform-agnostic messaging layer with uniform adapter interface
• Contains: ChannelAdapter interface, ChannelRegistry, per-platform adapter directories, PairingManager
• Key files: src/channels/types.ts, src/channels/registry.ts, src/channels/pairing.ts, src/channels/utils.ts

src/cli/:

• Purpose: CLI command definitions and entry point
• Contains: Commander.js command registrations, config loading helpers
• Key files: src/cli/index.ts (entry point), src/cli/start.ts, src/cli/tui.ts, src/cli/send.ts, src/cli/sessions.ts, src/cli/doctor.ts, src/cli/config-cmd.ts, src/cli/completion.ts, src/cli/shared.ts

src/config/:

• Purpose: Configuration loading and validation
• Contains: YAML loader with ${ENV_VAR} expansion, comprehensive Zod schema
• Key files: src/config/schema.ts (all config types), src/config/loader.ts (YAML parse + validate)

src/context/:

• Purpose: Conversation context management — token counting and history compaction
• Contains: Token estimator (rule-based, no tokenizer), compaction logic using delegation
• Key files: src/context/tokens.ts, src/context/compaction.ts

src/daemon/:

• Purpose: Daemon bootstrap — wires all subsystems together and manages lifecycle
• Contains: startDaemon() function (1088 lines), Lifecycle manager, model client factory, message router
• Key files: src/daemon/index.ts (main orchestration), src/daemon/lifecycle.ts

src/frontends/telegram/:

• Purpose: Legacy direct Telegram bot integration with confirmation UI
• Contains: Bot handlers, confirmation keyboard management
• Key files: src/frontends/telegram/bot.ts, src/frontends/telegram/handlers.ts, src/frontends/telegram/confirmations.ts

src/frontends/tui/:

• Purpose: Terminal user interface with two modes
• Contains: Minimal readline TUI, fullscreen React/Ink TUI, markdown rendering, slash commands
• Key files: src/frontends/tui/minimal.ts, src/frontends/tui/fullscreen.ts, src/frontends/tui/commands.ts, src/frontends/tui/markdown.ts

src/gateway/:

• Purpose: WebSocket JSON-RPC server + HTTP server + dashboard
• Contains: GatewayServer, Router (method dispatch), SessionBridge (WS → NativeAgent), LaneQueue (request serialization), auth, protocol, static file serving, Tailscale Serve integration
• Key files: src/gateway/server.ts, src/gateway/router.ts, src/gateway/session-bridge.ts, src/gateway/lane-queue.ts, src/gateway/protocol.ts, src/gateway/auth.ts, src/gateway/static.ts, src/gateway/tailscale.ts

src/gateway/handlers/:

• Purpose: JSON-RPC method handler implementations
• Contains: Handler factories for system, session, tool, agent, config, and pairing methods
• Key files: src/gateway/handlers/system.ts, src/gateway/handlers/sessions.ts, src/gateway/handlers/agent.ts, src/gateway/handlers/tools.ts, src/gateway/handlers/config.ts, src/gateway/handlers/pairing.ts

src/gateway/ui/:

• Purpose: Vanilla JS web dashboard served by gateway HTTP server
• Contains: HTML pages, CSS, client-side JavaScript
• Key files: src/gateway/ui/index.html, src/gateway/ui/chat.html, src/gateway/ui/style.css, src/gateway/ui/app.js, src/gateway/ui/lib/ws-client.js

src/hooks/:

• Purpose: Tool execution confirmation engine with glob-pattern matching
• Contains: HookEngine with pending confirmation queue
• Key files: src/hooks/engine.ts

src/mcp/:

• Purpose: Model Context Protocol integration — start external MCP servers and bridge their tools
• Contains: McpClient, McpManager, tool bridging utilities
• Key files: src/mcp/client.ts, src/mcp/manager.ts, src/mcp/bridge.ts

src/memory/:

• Purpose: Persistent memory system with keyword + vector hybrid search
• Contains: MemoryStore (namespace-based markdown files), VectorStore (SQLite), HybridSearch, embedding providers, text chunker
• Key files: src/memory/store.ts, src/memory/vector-store.ts, src/memory/hybrid-search.ts, src/memory/embeddings.ts, src/memory/chunker.ts

src/models/:

• Purpose: LLM provider client implementations and tier-based routing
• Contains: Provider clients, ModelRouter, retry logic, cost estimation, media helpers
• Key files: src/models/types.ts (core interfaces), src/models/router.ts, src/models/anthropic.ts, src/models/openai.ts, src/models/gemini.ts, src/models/bedrock.ts, src/models/github.ts, src/models/retry.ts, src/models/costs.ts, src/models/media.ts, src/models/capabilities.ts

src/models/local/:

• Purpose: Local model provider clients
• Contains: Ollama and llama.cpp client implementations
• Key files: src/models/local/ollama.ts, src/models/local/llamacpp.ts

src/prompt/:

• Purpose: System prompt assembly from template files
• Contains: Template search across directories (SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md)
• Key files: src/prompt/template.ts

src/sandbox/:

• Purpose: Docker container isolation for shell/process tool execution
• Contains: DockerSandbox (container lifecycle), SandboxManager (per-session containers), sandboxed tool wrappers
• Key files: src/sandbox/docker.ts, src/sandbox/manager.ts, src/sandbox/tools.ts

src/session/:

• Purpose: Conversation history persistence
• Contains: SessionStore (SQLite), SessionManager (in-memory cache), ManagedSession
• Key files: src/session/store.ts, src/session/manager.ts

src/skills/:

• Purpose: Pluggable skill system — load skills from bundled, managed, and workspace directories
• Contains: SkillRegistry, SkillInstaller, skill loader, skill type definitions
• Key files: src/skills/registry.ts, src/skills/installer.ts, src/skills/loader.ts, src/skills/types.ts

src/tools/:

• Purpose: Tool abstraction layer — registry, execution, policy enforcement
• Contains: ToolRegistry, ToolExecutor, ToolPolicy, type definitions
• Key files: src/tools/types.ts, src/tools/registry.ts, src/tools/executor.ts, src/tools/policy.ts

src/tools/builtin/:

• Purpose: Built-in tool implementations shipped with Flynn
• Contains: Shell exec, file operations, web fetch, memory ops, web search, media send, image analysis, session management, agent listing, cross-channel messaging, cron management
• Key files: src/tools/builtin/shell.ts, src/tools/builtin/file-read.ts, src/tools/builtin/file-write.ts, src/tools/builtin/file-edit.ts, src/tools/builtin/file-patch.ts, src/tools/builtin/file-list.ts, src/tools/builtin/web-fetch.ts, src/tools/builtin/web-search.ts, src/tools/builtin/memory-read.ts, src/tools/builtin/memory-write.ts, src/tools/builtin/memory-search.ts, src/tools/builtin/media-send.ts, src/tools/builtin/image-analyze.ts, src/tools/builtin/audio-transcribe.ts, src/tools/builtin/system-info.ts, src/tools/builtin/sessions.ts, src/tools/builtin/agents-list.ts, src/tools/builtin/message-send.ts, src/tools/builtin/cron.ts

src/tools/builtin/browser/:

• Purpose: Puppeteer-based browser automation tools
• Contains: BrowserManager (page lifecycle), browser tool implementations (navigate, screenshot, click, type, content, eval)
• Key files: src/tools/builtin/browser/manager.ts, src/tools/builtin/browser/tools.ts

src/tools/builtin/process/:

• Purpose: Background process management tools
• Contains: ProcessManager, tools for start/status/output/kill/list
• Key files: src/tools/builtin/process/manager.ts, src/tools/builtin/process/start.ts, src/tools/builtin/process/status.ts, src/tools/builtin/process/output.ts, src/tools/builtin/process/kill.ts, src/tools/builtin/process/list.ts

Key File Locations

Entry Points:

• src/cli/index.ts: CLI entry point (binary: flynn)
• src/daemon/index.ts: Daemon bootstrap (startDaemon()) — the central wiring point
• src/gateway/server.ts: Gateway WebSocket + HTTP server
• src/frontends/tui/minimal.ts: TUI readline mode
• src/frontends/tui/fullscreen.ts: TUI fullscreen Ink mode

Configuration:

• src/config/schema.ts: Complete Zod config schema — all types defined here
• src/config/loader.ts: YAML parse + env expansion + Zod validation
• tsconfig.json: TypeScript compiler config (strict, ES2022, NodeNext)
• package.json: Dependencies and scripts
• config/: Example/default config files directory

Core Logic:

• src/backends/native/agent.ts: NativeAgent — the AI tool loop
• src/backends/native/orchestrator.ts: AgentOrchestrator — delegation, compaction, memory
• src/models/router.ts: ModelRouter — tier-based model selection with fallback
• src/tools/executor.ts: ToolExecutor — policy check → hook check → execute
• src/channels/registry.ts: ChannelRegistry — adapter lifecycle + message routing
• src/daemon/index.ts: startDaemon() — wires everything together

Testing:

• Test files are co-located with source: src/path/to/file.test.ts alongside src/path/to/file.ts
• No separate test directory

Naming Conventions

Files:

• Source files: camelCase.ts (e.g., session-bridge.ts, lane-queue.ts) — actually kebab-case.ts
• React components: camelCase.ts in src/frontends/tui/components/
• Test files: *.test.ts suffix (e.g., agent.test.ts, registry.test.ts)
• Index files: index.ts barrel exports in every directory
• Type-only files: types.ts for pure type definitions

Directories:

• Feature-based: kebab-case/ (e.g., web-search, file-read)
• Platform subdirs: lowercase/ (e.g., telegram/, discord/, slack/)
• Nested features: parent/child/ (e.g., tools/builtin/browser/)

Exports:

• Every directory has an index.ts barrel file that re-exports public APIs
• Types use export type for type-only exports
• Registration chain flows: implementation → builtin/index.ts → tools/index.ts → daemon/index.ts

Where to Add New Code

New Channel Adapter:

• Create directory: src/channels/<platform>/
• Create: adapter.ts (implements ChannelAdapter), index.ts (re-exports)
• Add test: adapter.test.ts
• Register in: src/channels/index.ts (export), src/daemon/index.ts (instantiate + register)
• Add config: src/config/schema.ts (new optional schema block)

New Model Provider:

• Create: src/models/<provider>.ts (implements ModelClient)
• Add export: src/models/index.ts
• Add case: src/daemon/index.ts → createClientFromConfig() switch statement
• Add config: src/config/schema.ts → modelConfigBaseSchema.provider enum

New Tool:

• Static tool (no deps): Create src/tools/builtin/<name>.ts, export const
• Factory tool (needs deps): Create src/tools/builtin/<name>.ts, export function
• Add to: src/tools/builtin/index.ts (export + add to allBuiltinTools if static)
• Add to: src/tools/index.ts (re-export)
• Register in: src/daemon/index.ts (call factory + register with toolRegistry)
• Add to profiles: src/tools/policy.ts → PROFILE_TOOLS if needed

New Tool Group (multi-tool):

• Create directory: src/tools/builtin/<group>/
• Create: manager.ts (shared state), individual tool files, index.ts
• Follow pattern of src/tools/builtin/process/ or src/tools/builtin/browser/

New Gateway Handler:

• Create: src/gateway/handlers/<domain>.ts (export createXxxHandlers())
• Add to: src/gateway/handlers/index.ts
• Register in: src/gateway/server.ts → registerHandlers()

New Automation Type:

• Create: src/automation/<type>.ts
• If it produces messages: implement ChannelAdapter interface
• Add to: src/automation/index.ts
• Register in: src/daemon/index.ts
• Add config: src/config/schema.ts → automationSchema

New CLI Command:

• Create: src/cli/<command>.ts → export registerXxxCommand(program)
• Register in: src/cli/index.ts

Utilities:

• Shared helpers: Place in the most specific layer that uses them
• Cross-cutting: src/channels/utils.ts for channel utils, src/models/media.ts for media utils
• No global utils/ directory — utilities are co-located with their domain

Special Directories

dist/:

• Purpose: Compiled JavaScript output
• Generated: Yes (by pnpm build / tsc)
• Committed: No (in .gitignore)

node_modules/:

• Purpose: Installed dependencies
• Generated: Yes (by pnpm install)
• Committed: No (in .gitignore)

config/:

• Purpose: Example/default configuration files
• Generated: No
• Committed: Yes

src/gateway/ui/:

• Purpose: Static web dashboard (vanilla HTML/CSS/JS, not compiled)
• Generated: No — hand-written vanilla JS
• Committed: Yes
• Note: Served by the gateway HTTP server at runtime from dist/gateway/ui/

.planning/:

• Purpose: GSD planning and analysis documents
• Generated: By analysis tools
• Committed: Yes

docs/plans/:

• Purpose: Feature planning documents and state tracking
• Generated: No
• Committed: Yes

---

Structure analysis: 2025-02-09