flynn/docs

Flynn Documentation (Start Here)

This documentation is written to be useful to both humans and AI agents. If you want a fast mental model, read the architecture diagram first.

Reading Order

1. Architecture overview (agent-oriented)
   • docs/architecture/AGENT_DIAGRAM.md
   • docs/architecture/AGENT_REPO_MAP.md
   • docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md
   • docs/architecture/TYPESCRIPT_MAP.md
   • docs/architecture/SYMBOL_INDEX.md
   • docs/architecture/CONTRIBUTOR_MAP.md
2. Security boundary (safe-by-default personal agent)
   • docs/security/SAFE_PERSONAL_AGENT.md
3. Gateway API (WebSocket JSON-RPC)
   • docs/api/PROTOCOL.md
4. Tool contracts and policy/execution details
   • docs/api/TOOLS.md
5. Production and performance
   • docs/deployment/PRODUCTION.md
   • docs/performance/TUNING.md
6. Operations runbooks
   • docs/operations/OPERATOR_PACK.md
   • docs/operations/GOOGLE_AUTH.md
   • docs/operations/COMPANION_RELEASE_BUNDLE.md

Quick Map (One Diagram)

flowchart TD
  U[User on chat surface] --> CA[ChannelAdapter]
  U --> GW[Gateway WS/HTTP + Web UI]

  CA --> RT[Routing + Sessions]
  GW --> RT

  RT --> OR[AgentOrchestrator]
  OR --> NA[NativeAgent tool loop]
  NA --> MR[ModelRouter]
  MR --> MC[ModelClient -> provider]

  NA --> TP[ToolPolicy + ToolRegistry]
  TP --> TE[ToolExecutor\nhooks + enforcement + audit]