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

```bash
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*