flynn/docs/architecture/AGENT_REPO_MAP.md

Agent Repo Map

This file is an agent-facing operational map of the Flynn repo: entrypoints, key modules, conventions, config schema anchors, and debug workflows.

Entry Points

• Daemon start: src/cli/index.ts -> src/daemon/index.ts#startDaemon
• One-shot send: src/cli/send.ts
• TUI:
  • Minimal: src/frontends/tui/minimal.ts
  • Fullscreen Ink app: src/frontends/tui/components/App.tsx
• Gateway server: src/gateway/server.ts

Core Message Flow

1. Channel ingress/gateway request -> src/daemon/routing.ts
2. Session/orchestration -> src/backends/native/orchestrator.ts
3. Agent loop/tool execution -> src/backends/native/agent.ts
4. Model dispatch -> src/models/router.ts + provider clients in src/models/*

High-Value Modules

• Config schema + defaults:
  • src/config/schema.ts
  • config/default.yaml
  • config/profiles/*.overlay.yaml (profile overlays)
• Model wiring:
  • src/daemon/models.ts
  • src/models/router.ts
  • src/models/openai.ts, src/models/anthropic.ts, src/models/gemini.ts, src/models/bedrock.ts, src/models/github.ts, src/models/local/*
• Tool registration chain:
  • Tool impl: src/tools/builtin/*
  • Export: src/tools/builtin/index.ts
  • Registry/bootstrap: src/daemon/index.ts, src/daemon/tools.ts
• Channel adapters:
  • src/channels/*/adapter.ts
  • Registration: src/daemon/channels.ts
• Auth stores:
  • OpenAI/Anthropic/etc: src/auth/*
  • Google services: src/auth/google.ts + src/google/oauth.ts
• Observability:
  • Audit logger: src/audit/*
  • Doctor checks: src/cli/doctor.ts

Conventions

• TypeScript strict mode, NodeNext modules.
• Local imports use .js extension.
• Keep provider-specific branches localized in provider clients; prefer shared helpers for cross-service auth logic.
• Tests use Vitest (*.test.ts).

Config Schema Anchors

• Model tiers and fallback chain: models.* in src/config/schema.ts
• Tool policy and profiles: tools.*
• Automation integrations:
  • Gmail watcher: automation.gmail
  • Google tools: automation.gcal, automation.gdocs, automation.gdrive, automation.gtasks
• Server/gateway behavior: server.*

Run and Debug

pnpm dev                 # daemon watch mode
pnpm tui                 # minimal terminal UI
pnpm tui:fs              # fullscreen UI
pnpm test:run            # full test run once
pnpm lint
pnpm typecheck

Focused debug commands:

pnpm test:run src/models/router.test.ts src/models/openai.oauth.test.ts
pnpm test:run src/tools/builtin/gmail.test.ts src/automation/gmail.test.ts
pnpm test:run src/cli/doctor.test.ts

Config profile sync:

pnpm config:profiles:generate
pnpm config:profiles:check