High-level overview of how Flutch platform works.

How It Works

markdown
┌────────────────────────────────────────────────────────────┐
│                   Flutch Infrastructure                    │
│                                                            │
│  ┌────────────────────────────────────────────────────┐    │
│  │         AI Framework (LangGraph/LangChain/etc)     │    │
│  │                                                    │    │
│  │  ┌──────────────────────────────────────────┐      │    │
│  │  │         Your AI Agent                    │      │    │
│  │  │  • Business logic                        │      │    │
│  │  │  • Prompts & tools                       │      │    │
│  │  │  • Conversation flow                     │      │    │
│  │  └──────────────────────────────────────────┘      │    │
│  │                                                    │    │
│  └────────────────────────────────────────────────────┘    │
│                                                            │
│  Flutch provides:                                          │
│  • Chat UI (Web, Telegram, Discord)                        │
│  • Admin Console (console.flutch.ai)                       │
│  • State management & persistence                          │
│  • Analytics & monitoring                                  │
│  • Multi-LLM support (OpenAI, Anthropic, Google, Azure)    │
│  • Deployment & versioning                                 │
└────────────────────────────────────────────────────────────┘

You focus on: Your agent logic Flutch handles: Infrastructure, UI, analytics, distribution

Graph vs Agent

Graph = Workflow code (template)

Deployed with flutch graph deploy
Defines execution logic (nodes, edges, state)
Versioned (1.0.0, 1.1.0, 2.0.0)

Agent = Configured instance

Created in console UI
Uses a specific graph version
Has unique configuration (prompt, model, tools)

Example:

markdown
Graph: "acme.support::1.0.0" (deployed once)
  ├─ Agent "Sales Bot" → GPT-4, sales prompt, CRM tools
  ├─ Agent "Support Bot" → Claude, support prompt, docs tools
  └─ Agent "Tech Bot" → GPT-4, tech prompt, debug tools

One graph = many agents with different configs.

Request Flow

markdown
User sends message
       ↓
Platform authenticates
       ↓
Platform finds agent config
  - Which graph version?
  - What prompt/model/tools?
       ↓
Platform routes to Graph Service
       ↓
Graph Service executes
  - Loads conversation state
  - Applies agent config
  - Runs workflow nodes
  - Calls LLM/tools
  - Saves state
       ↓
Graph Service returns response
       ↓
Platform logs & tracks metrics
       ↓
User receives response

Deployment Flow

markdown
Developer writes code
       ↓
flutch graph deploy
       ↓
CLI validates & uploads
       ↓
Platform builds container
  - Your workflow code
  - Runtime dependencies
  - Flutch SDK
       ↓
Platform deploys container
       ↓
Graph Service running
  ✅ Ready to power agents

Local Development

bash
# Register graph for development
flutch graph register

# Start local server
npm run dev  # runs on localhost:3100

# Test via platform
flutch graph test "Hello"

How it works:

bash
flutch graph test "Hello"
       ↓
Platform creates operation
       ↓
CLI calls localhost:3100
       ↓
Local graph executes
       ↓
Results sent to platform
       ↓
CLI displays response + trace link

Full platform integration while developing locally.

State Management

Graph Services use checkpointers to persist conversation state:

Redis - Recommended for production (fast, TTL support)
PostgreSQL - Relational storage
MongoDB - Document storage
Memory - Development only (not persistent)

Each conversation has unique threadId. State automatically loaded/saved between turns.

Security

Network isolation:

Graph Services isolated from internet
Only Platform can call Graph Services
External APIs via secure proxy

Authentication layers:

User → Platform: API key or OAuth
Platform → Graph Service: Platform token
Graph Service → External APIs: Your API keys (encrypted)

State isolation:

Each conversation isolated by threadId
No cross-conversation access
RBAC in console UI