AgentFlow — Project Overview

1. Executive Summary & Problem Solved

AgentFlow is a high-complexity autonomous multi-agent task execution platform. Users declare high-level objectives in natural language; an Orchestrator Agent intelligently decomposes these into ordered sub-tasks, dispatches them to specialized Worker Agents, and provides live telemetry streaming of every execution step. The entire pipeline is deterministic, fully typed end-to-end in TypeScript, and operates without any Python dependencies or LangChain abstractions.

Core Problem Solved: Complex multi-step objectives (e.g., "Build a REST API for a bookstore with auth, testing, and deployment config") require human project management to decompose, assign, track, and debug. AgentFlow automates this entire lifecycle — planning, delegation, execution monitoring, and result aggregation — within a single deterministic TypeScript runtime.

Key Capabilities:

• Goal-in → structured task graph out (deterministic decomposition)
• Pluggable worker agent pool with capability-based routing
• Real-time telemetry via SSE streaming (task state transitions, LLM tokens, execution duration, errors)
• Full type safety from UI to database (TanStack Start server functions + MongoDB types)
• Persistent execution state in MongoDB for crash recovery and audit trails

---

2. Target Users & Value Proposition

User Segment	Value Proposition
Engineering Teams	Delegate multi-file code generation, refactoring, and documentation tasks to specialized workers with full observability
Technical Project Managers	Define goals in plain language; receive structured execution plans and live progress dashboards
Solo Developers	Automate repetitive multi-step workflows (scaffold → implement → test → document) with a single goal statement
DevOps / Platform Engineers	Use worker agents for infrastructure tasks (provisioning, config generation, deployment validation) with audit-grade telemetry

Differentiators:

• No black boxes: Every agent decision, LLM prompt, and tool call is logged and streamed — full reproducibility
• Pure TypeScript: Single runtime, no language bridging, unified type system from database to UI
• Deterministic by design: Agent behavior is governed by explicit state machines and typed contracts, not framework magic

---

3. Tech Stack & Architectural Decisions

Stack Overview

┌─────────────────────────────────────────────────────┐
│                   Client (SPA)                       │
│  React + TanStack Start Router + Tailwind CSS v4    │
│  Telemetry Dashboard · Task Input · Result Viewer   │
└──────────────────┬──────────────────────────────────┘
                   │ Server Functions (RPC / SSE)
┌──────────────────▼──────────────────────────────────┐
│              TanStack Start Server                    │
│  Agent Runtime · Orchestrator · Worker Pool · API    │
│  Type-safe server functions + file-based routes      │
└──────────────────┬──────────────────────────────────┘
                   │ Driver: mongodb-memory-server (dev)
┌──────────────────▼──────────────────────────────────┐
│              MongoDB (v7+)                           │
│  Tasks · Agents · Executions · Telemetry · Convos   │
└─────────────────────────────────────────────────────┘

External: OpenRouter (LLM API) — model routing, key management, usage tracking

Decision Rationale

Choice	Rationale
TanStack Start	Full-stack TS framework providing server functions (type-safe RPC without REST boilerplate), file-based routing, and seamless client/server type sharing. Ideal for SSE streaming endpoints and server-side agent logic co-located with API routes.
TypeScript (strict)	Single-language constraint eliminates cross-runtime serialization bugs. Agent interfaces, task schemas, and telemetry types are shared from DB models → server functions → UI components via TanStack's generated types.
Tailwind CSS v4	Utility-first styling for the telemetry dashboard with CSS variables for theming. V4's compiler-first approach integrates cleanly with TanStack Start's Vite-based build pipeline.
OpenRouter	Unified API for multiple LLM providers (GPT-4, Claude, Gemini) with deterministic model selection per agent role. Supports structured JSON output (critical for task decomposition). API key management abstracted behind a typed LLMProvider interface.
MongoDB	Document model naturally fits agent state (nested task graphs, variable execution logs, conversation histories). Flexible schema accommodates evolving agent capabilities without migrations. Native TypeScript driver with strict typing.
No Python / No LangChain	Eliminates process boundaries, serialization overhead, and framework abstraction leakage. The agent framework is a custom, ~2000 LOC TypeScript runtime with explicit interfaces — every decision is inspectable and modifiable.

Core Architecture Layers

src/
├── agents/                          # Agent framework (no LangChain)
│   ├── orchestrator/                # Goal decomposition engine
│   │   ├── OrchestratorAgent.ts     # Entry agent: goal → task graph
│   │   ├── DecompositionEngine.ts   # Recursive task splitting w/ LLM
│   │   └── types.ts                 # Goal, TaskGraph, SubTask types
│   ├── workers/                     # Specialized executors
│   │   ├── WorkerAgent.ts           # Base class: capability, execute(), stream()
│   │   ├── CodeWorker.ts            # Code generation/execution
│   │   ├── ResearchWorker.ts        # Info gathering / analysis
│   │   ├── WritingWorker.ts         # Documentation / content
│   │   └── registry.ts              # Capability-based worker routing
│   ├── llm/                         # LLM abstraction layer
│   │   ├── OpenRouterProvider.ts    # OpenRouter client w/ JSON mode
│   │   ├── prompts.ts               # System prompts per agent role
│   │   └── types.ts                 # Completion, TokenUsage, Message types
│   ├── state-machine.ts             # Task lifecycle FSM (pending→running→done|failed)
│   └── index.ts                     # Agent factory & wiring
├── server/                          # TanStack Start server
│   ├── routes/                      # File-based routes + server functions
│   │   ├── api/
│   │   │   ├── goals.$post.ts       # Submit goal → returns taskGraphId
│   │   │   ├── tasks.$get.ts        # List/query tasks
│   │   │   └── telemetry.$stream.ts # SSE stream of execution events
│   │   └── dashboard/               # Dashboard UI route
│   ├── middleware/                  # Auth, rate limiting, request logging
│   └── env.ts                       # Validated env via TanStack Start
├── database/                        # MongoDB data layer
│   ├── collections/
│   │   ├── goals.ts                 # { id, description, status, createdAt }
│   │   ├── tasks.ts                 # { id, goalId, parentId, status, assignee, priority, deps[] }
│   │   ├── executions.ts            # { id, taskId, workerType, logs[], tokensUsed, duration, error? }
│   │   ├── telemetry.ts             # { id, taskId, eventType, data, timestamp } (time-series)
│