Skip to content

Data Flow

Data Flow

Quick Reference

Pattern: Request-Response (Web API) + Streaming (LLM) + Event-Driven (Analytics)

Protocol: REST (Web API), Server-Sent Events (LLM streaming), WebSocket (SDK)

Serialization: JSON (API), NDJSON (streaming)

Key Integration Points: OpenRouter, Stripe, PostHog, GitHub OAuth

End-to-End Data Flow

graph TB
    User["👤 User"]

    subgraph Input["📥 Input Layer"]
        CLI_INPUT["CLI Prompt"]
        SDK_INPUT["SDK API Call"]
        WEB_INPUT["Web Dashboard"]
    end

    subgraph Processing["⚙️ Processing Layer"]
        AGENT_RT["Agent Runtime"]
        STEP_RUNNER["Step Runner"]
        TOOL_EXEC["Tool Executor"]
        CONTEXT["Context Pruner"]
    end

    subgraph LLM_Layer["🧠 LLM Layer"]
        OPENROUTER["OpenRouter"]
        CLAUDE["Claude"]
        GPT["GPT"]
        DEEPSEEK["DeepSeek"]
    end

    subgraph Output["📤 Output Layer"]
        FILE_CHANGES["File Changes"]
        TERMINAL_OUT["Terminal Output"]
        RESPONSE["User Response"]
    end

    subgraph Data["🗄️ Data Persistence"]
        PG["PostgreSQL"]
        BQ["BigQuery"]
    end

    User --> Input
    Input --> Processing
    Processing --> LLM_Layer
    LLM_Layer --> Processing
    Processing --> Output
    Processing --> Data
    Output --> User

CLI Agent Flow

The primary data flow when a user interacts with Codebuff via CLI:

sequenceDiagram
    participant U as User (Terminal)
    participant CLI as CLI (OpenTUI)
    participant ZS as Zustand Store
    participant SDK as SDK Client
    participant RT as Agent Runtime
    participant LLM as OpenRouter LLM
    participant FS as File System
    participant DB as PostgreSQL

    U->>CLI: Type prompt
    CLI->>ZS: Update chat state
    CLI->>SDK: client.run(prompt)
    SDK->>RT: Initialize agent run
    RT->>DB: Create agentRun record

    loop Each Agent Step
        RT->>LLM: Send messages (streaming)
        LLM-->>RT: Token stream (SSE)
        RT->>RT: Parse tool calls from stream

        alt File Read
            RT->>FS: read_files(paths)
            FS-->>RT: File contents
        else File Write
            RT->>FS: write_file(path, content)
            FS-->>RT: Success
        else Code Search
            RT->>FS: code_search(query)
            FS-->>RT: Matches
        else Terminal Command
            RT->>FS: run_terminal_command(cmd)
            FS-->>RT: Output
        else Spawn Sub-Agent
            RT->>RT: spawn_agents(config)
            Note over RT: Recursive agent execution
        end

        RT->>DB: Create agentStep record
        RT->>DB: Create message record (tokens, cost)
        RT-->>CLI: Stream progress update
        CLI-->>U: Render update (Ink/React)
    end

    RT->>DB: Update agentRun (completed)
    RT-->>SDK: RunResult
    SDK-->>CLI: Final result
    CLI->>ZS: Update state
    CLI-->>U: Display summary

SDK Programmatic Flow

How the SDK integrates into third-party applications:

sequenceDiagram
    participant App as Application
    participant SDK as CodebuffClient
    participant Auth as Credentials
    participant Run as Run Engine
    participant State as RunState Machine
    participant LLM as LLM Provider

    App->>SDK: new CodebuffClient(config)
    SDK->>Auth: Validate API key

    App->>SDK: client.run(options)
    SDK->>Run: Initialize run
    Run->>State: Create state machine

    loop Steps
        State->>LLM: Prompt with context
        LLM-->>State: Streaming response
        State->>State: Execute tool calls
        State->>App: handleEvent(progress)
    end

    Run-->>App: RunResult

Credit Billing Flow

How credits are tracked and consumed:

sequenceDiagram
    participant U as User
    participant API as API Server
    participant BIL as Billing Service
    participant CL as Credit Ledger
    participant STR as Stripe
    participant DB as PostgreSQL

    U->>API: Make LLM call
    API->>CL: Check available credits
    CL->>DB: Query active balances
    DB-->>CL: Balance info

    alt Sufficient Credits
        CL-->>API: Approved
        API->>API: Execute LLM call
        API->>CL: Deduct credits
        CL->>DB: Insert ledger entry
    else Insufficient Credits
        CL-->>API: Insufficient

        alt Auto-topup Enabled
            API->>BIL: Trigger auto-topup
            BIL->>STR: Charge card
            STR-->>BIL: Payment success
            BIL->>CL: Grant credits
            CL->>DB: Insert grant entry
            API->>API: Execute LLM call
        else No Auto-topup
            API-->>U: Credit limit reached
        end
    end

Authentication Flow

sequenceDiagram
    participant U as User
    participant CLI as CLI
    participant WEB as Web App
    participant AUTH as NextAuth
    participant GH as GitHub OAuth
    participant DB as PostgreSQL

    alt CLI Login
        U->>CLI: codebuff login
        CLI->>WEB: Open browser (auth URL)
        U->>WEB: Click "Login with GitHub"
        WEB->>GH: OAuth redirect
        GH-->>WEB: Authorization code
        WEB->>AUTH: Exchange for session
        AUTH->>DB: Create session (type: cli)
        AUTH-->>CLI: Session token
        CLI->>CLI: Store token locally
    else API Key / PAT
        U->>CLI: codebuff --api-key=...
        CLI->>CLI: Store in credentials
    end

External Integrations

Service	Protocol	Direction	Data	Rate Limit
OpenRouter	REST + SSE	Bidirectional	LLM prompts/responses	Per-model limits
Stripe	REST + Webhooks	Bidirectional	Payments, subscriptions	Standard Stripe limits
GitHub OAuth	OAuth 2.0	Bidirectional	Authentication tokens	Standard GitHub limits
PostHog	REST	Outbound	Analytics events	Batch optimized
Discord	REST + Bot API	Bidirectional	Notifications, commands	Discord rate limits
Loops	REST	Outbound	Email automation	API key based
BigQuery	REST	Outbound	Analytics data	GCP quotas

Agent Store Data Flow

graph LR
    DEV["👨‍💻 Developer"]
    CLI_PUB["CLI publish"]
    API_PUB["Publisher API"]
    DB_PUB["PostgreSQL"]
    STORE["Agent Store (Web)"]
    CONSUMER["Consumer"]
    CLI_USE["CLI use"]

    DEV -->|"codebuff publish"| CLI_PUB
    CLI_PUB -->|"POST /api/agents"| API_PUB
    API_PUB -->|"Insert"| DB_PUB
    DB_PUB -->|"Query"| STORE
    CONSUMER -->|"Browse"| STORE
    STORE -->|"Install"| CLI_USE

Architecture — System design
Database — Schema details
API Reference — API endpoints