flynn/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-02-09

Languages

Primary:

• TypeScript 5.7+ - All source code in src/
• JSX (react-jsx) - TUI components in src/frontends/tui/components/

Secondary:

• JavaScript (vanilla) - Gateway web dashboard in src/gateway/ui/ (HTML/CSS/JS, no framework)
• SQL - Inline SQLite schema in src/session/store.ts and src/memory/vector-store.ts
• YAML - Configuration files in config/

Runtime

Environment:

• Node.js >= 22.0.0 (required by engines in package.json)
• ES2022 target, NodeNext module system

Package Manager:

• pnpm
• Lockfile: pnpm-lock.yaml (present, ~6500 lines)

Frameworks

Core:

• None (custom daemon architecture — no Express, Fastify, or similar)
• Raw http.createServer + ws WebSocket server for the gateway (src/gateway/server.ts)

CLI:

• Commander 14.x - CLI argument parsing (src/cli/index.ts)
• Ink 6.x + React 19.x - Terminal UI framework (src/frontends/tui/)

Testing:

• Vitest 3.x - Test runner and assertion library

Build/Dev:

• TypeScript compiler (tsc) - Production builds
• tsx 4.x - Development mode with watch (pnpm dev)

Key Dependencies

Critical (AI/Model Providers):

• @anthropic-ai/sdk ^0.39.0 - Anthropic Claude API client (src/models/anthropic.ts)
• openai ^4.0.0 - OpenAI API client, also used for OpenRouter/ZhipuAI/xAI/GitHub Models (src/models/openai.ts, src/models/github.ts)
• @google/generative-ai ^0.24.1 - Google Gemini API client (src/models/gemini.ts)
• @aws-sdk/client-bedrock-runtime ^3.985.0 - AWS Bedrock for model inference (src/models/bedrock.ts)
• ollama ^0.5.0 - Ollama local model client (src/models/local/ollama.ts)

Critical (Channel Adapters):

• grammy ^1.35.0 - Telegram bot framework (src/channels/telegram/)
• discord.js ^14.25.1 - Discord bot library (src/channels/discord/)
• @slack/bolt ^4.6.0 - Slack bot framework (src/channels/slack/)
• whatsapp-web.js ^1.34.6 - WhatsApp Web client (src/channels/whatsapp/)

Critical (Data):

• better-sqlite3 ^11.0.0 - SQLite for sessions (src/session/store.ts) and vector storage (src/memory/vector-store.ts)
• zod ^3.24.0 - Configuration schema validation (src/config/schema.ts)
• yaml ^2.7.0 - Config file parsing (src/config/loader.ts)

Infrastructure:

• ws ^8.19.0 - WebSocket server for gateway (src/gateway/server.ts)
• @modelcontextprotocol/sdk ^1.26.0 - MCP client for external tool servers (src/mcp/client.ts)
• googleapis ^148.0.0 - Gmail API integration (src/automation/gmail.ts)
• croner ^10.0.1 - Cron job scheduling (src/automation/cron.ts)
• puppeteer-core ^24.37.2 - Browser automation for web tools (src/tools/builtin/browser/)

Content Processing:

• @mozilla/readability ^0.5.0 - Article extraction from web pages (src/tools/builtin/web-fetch.ts)
• linkedom ^0.18.0 - Server-side DOM for Readability (src/tools/builtin/web-fetch.ts)
• turndown ^7.2.0 - HTML to Markdown conversion (src/tools/builtin/web-fetch.ts)
• marked ^17.0.1 + marked-terminal ^7.3.0 - Markdown rendering in terminal
• cli-highlight ^2.1.11 - Syntax highlighting in terminal

Configuration

Format:

• YAML config file with ${ENV_VAR} expansion support
• Zod schema validation at load time (src/config/schema.ts)
• Config loaded via loadConfig() in src/config/loader.ts

Config Location:

• Default template: config/default.yaml
• User config: ~/.config/flynn/config.yaml (conventional)
• CLI flag: --config <path> on flynn start

Data Directory:

• Default: ~/.local/share/flynn/
• Override: FLYNN_DATA_DIR environment variable
• Contains: sessions.db, vectors.db, memory/ directory

Auth Storage:

• GitHub OAuth tokens: ~/.config/flynn/auth.json (0600 permissions)
• Gmail OAuth tokens: ~/.config/flynn/gmail-token.json
• Gmail credentials: ~/.config/flynn/gmail-credentials.json

Key Environment Variables:

• ANTHROPIC_API_KEY - Anthropic API authentication
• OPENAI_API_KEY - OpenAI API authentication
• GOOGLE_API_KEY - Gemini API authentication
• GITHUB_TOKEN - GitHub Models / Copilot authentication
• AWS_REGION - AWS Bedrock region (default: us-east-1)
• OPENROUTER_API_KEY - OpenRouter API authentication
• ZHIPUAI_API_KEY - ZhipuAI API authentication
• XAI_API_KEY - xAI (Grok) API authentication
• VOYAGE_API_KEY - Voyage AI embeddings authentication
• FLYNN_TELEGRAM_TOKEN - Telegram bot token (referenced in default config)
• FLYNN_DATA_DIR - Custom data directory override

Build:

• tsconfig.json - TypeScript compiler config
  • Target: ES2022
  • Module: NodeNext
  • ModuleResolution: NodeNext
  • Strict mode enabled
  • JSX: react-jsx
  • Source maps, declarations, and declaration maps enabled
  • Root: src/, Output: dist/

Platform Requirements

Development:

• Node.js >= 22.0.0
• pnpm (package manager)
• TypeScript 5.7+

Production:

• Node.js >= 22.0.0
• SQLite3 (native binding via better-sqlite3)

Optional Runtime Dependencies:

• Docker - For sandbox container execution (src/sandbox/)
• Tailscale CLI - For Tailscale Serve gateway exposure (src/gateway/tailscale.ts)
• Chromium/Chrome - For browser tools via puppeteer-core (src/tools/builtin/browser/)

Build Commands

pnpm build                    # Compile TypeScript to dist/
pnpm dev                      # Run daemon with tsx watch mode
pnpm start                    # Start production build (node dist/cli/index.js start)
pnpm tui                      # Run TUI (readline mode)
pnpm tui:fs                   # Run TUI (fullscreen React/Ink mode)
pnpm tui:dev                  # Run TUI with watch mode
pnpm test                     # Run Vitest in watch mode
pnpm test:run                 # Run Vitest once
pnpm lint                     # ESLint
pnpm typecheck                # tsc --noEmit

---

Stack analysis: 2026-02-09