# dustland/agentok architecture

> Architecture diagram of the GitHub repository dustland/agentok, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dustland/agentok
- Repository: https://github.com/dustland/agentok

## Overview

##### Project type and purpose
- Agentok Studio is a full-stack web application for visually composing agent workflows (AG2-based) with drag-and-drop.
- Frontend is built with Next.js + React, Backend is FastAPI, Database is Supabase, Code generation and execution via AG2.

##### Focus: the `frontend/src/components/flow` sub-system
- This folder implements the visual flow editor: nodes, edges, configuration panels, preview, and code-generation integration.
- It uses ReactFlow for diagramming, custom node/edge components, option controls, and communicates with state hooks, service libraries, and API routes.

- FlowEditor (flow-editor.tsx)
- FlowCanvas (flow-canvas.tsx)
- NodeList / NodeButton (node-list.tsx, node-button.tsx)
- Config Panel (flow-config.tsx)
- Preview / JSON view (flow-preview.tsx, flow-json.tsx)
b. Sub-components (lighter green)
- Node components (assistant.tsx, user.tsx, group.tsx, etc.)
- Edge components (converse-edge.tsx, tool-panel.tsx)
- Option controls (select, range, text under `flow/option`)
- React state & hooks (e.g., useDebounce, flow hooks if any)
- Global store (e.g., Zustand in `frontend/src/store/*`)
- flow.ts library (`frontend/src/lib/flow.ts`) – serialization & code-prep
- fetcher.ts hook for HTTP calls
- Next.js API routes (`frontend/src/app/api/codegen/*`, `projects`, `templates`)
- FastAPI service endpoints (`/api/codegen/extract`, `/api/projects`, etc.)
- Supabase (auth + DB)
- AG2 execution engine (Docker or local)

1) User drags/drops node or edge → FlowEditor UI
2) UI triggers ReactFlow events → updates React state / store
3) On configuration changes → OptionControls update Flow state → flow.ts serializes to JSON
4) “Preview” / “Generate Code” button → calls Next.js API → forwards to FastAPI `/codegen/extract`
5) FastAPI uses AG2 to generate Python code → returns code & execution logs → displayed in Preview
6) Saving workflow → UI calls `/api/projects` via fetcher → Supabase persists JSON

##### Architectural patterns & principles
- Component-based UI with single-source Flow state
- Separation of concerns:
- Presentation (React + ReactFlow components)
- State & business logic (Zustand store + flow.ts)
- Service layer (fetcher hooks + Next.js API)
- Persistence & compute (Supabase + FastAPI + AG2)
- One-way data flow: UI → State → API → DB/Compute → UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer (frontend/src/components/flow)" 
        FlowEditor["FlowEditor"]:::ui
        FlowCanvas["FlowCanvas"]:::ui
        NodeList["NodeList"]:::ui
        NodeButton["NodeButton"]:::ui
        ConfigPanel["Config Panel"]:::ui
        PreviewPanel["Preview Panel"]:::ui
        JSONView["JSON View"]:::ui
        subgraph "Sub-components"
            NodeComponents["Node Components"]:::ui
            EdgeComponents["Edge Components"]:::ui
            OptionControls["Option Controls"]:::ui
        end
    end

    subgraph "State & Services"
        ZustandStore["Global Store"]:::service
        DebounceHook["use-debounce.ts"]:::service
        FetcherHook["fetcher.ts"]:::service
        FlowLib["flow.ts"]:::service
    end

    subgraph "Next.js API Routes"
        API_CodegenExtract["/api/codegen/extract"]:::api
        API_CodegenRoot["/api/codegen"]:::api
        API_Projects["/api/projects"]:::api
        API_ProjectId["/api/projects/[id]"]:::api
        API_TemplatesList["/api/templates"]:::api
        API_TemplateId["/api/templates/[id]"]:::api
    end

    subgraph "Backend & Compute"
        FastAPI["FastAPI Service (agentok_api.main:app)"]:::api
    end

    subgraph "Data & External Services"
        subgraph Supabase
            SupabaseClient["Client"]:::data
            SupabaseAuth["Auth"]:::data
            SupabaseMiddleware["Middleware"]:::data
            SupabaseServer["Server"]:::data
        end
        AG2["AG2 Execution Engine"]:::data
    end

    %% Relationships
    FlowEditor -->|uses| FlowCanvas
    FlowEditor --> NodeList
    NodeList --> NodeButton
    FlowEditor --> ConfigPanel
    ConfigPanel --> OptionControls
    FlowEditor --> PreviewPanel
    FlowEditor --> JSONView
    FlowCanvas -->|"diagramming"| NodeComponents
    FlowCanvas --> EdgeComponents
    OptionControls --> FlowLib
    FlowEditor -->|"updates state"| ZustandStore
    FlowLib --> JSONView
    PreviewPanel -->|"calls codegen"| API_CodegenExtract
    FlowEditor -->|"save workflow"| API_Projects
    API_CodegenExtract -->|"forwards"| FastAPI
    API_Projects -->|"forwards"| FastAPI
    FastAPI -->|"persist"| SupabaseClient
    FastAPI -->|"exec"| AG2
    FastAPI --> SupabaseAuth
    FastAPI --> SupabaseMiddleware
    FastAPI --> SupabaseServer

    %% Click Events
    click FlowEditor "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/flow-editor.tsx"
    click FlowCanvas "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/flow-canvas.tsx"
    click NodeList "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/node-list.tsx"
    click NodeButton "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/node-button.tsx"
    click ConfigPanel "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/flow-config.tsx"
    click PreviewPanel "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/flow-preview.tsx"
    click JSONView "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/json.tsx"
    click NodeComponents "https://github.com/dustland/agentok/tree/main/frontend/src/components/flow/node/"
    click EdgeComponents "https://github.com/dustland/agentok/blob/main/frontend/src/components/flow/edge/converse-edge.tsx"
    click OptionControls "https://github.com/dustland/agentok/tree/main/frontend/src/components/flow/option/"
    click DebounceHook "https://github.com/dustland/agentok/blob/main/frontend/src/hooks/use-debounce.ts"
    click FetcherHook "https://github.com/dustland/agentok/blob/main/frontend/src/hooks/fetcher.ts"
    click ZustandStore "https://github.com/dustland/agentok/tree/main/frontend/src/store/"
    click FlowLib "https://github.com/dustland/agentok/blob/main/frontend/src/lib/flow.ts"
    click API_CodegenExtract "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/codegen/extract/route.ts"
    click API_CodegenRoot "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/codegen/route.ts"
    click API_Projects "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/projects/route.ts"
    click API_ProjectId "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/projects/[id]/route.ts"
    click API_TemplatesList "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/templates/route.ts"
    click API_TemplateId "https://github.com/dustland/agentok/blob/main/frontend/src/app/api/templates/[id]/route.ts"
    click SupabaseClient "https://github.com/dustland/agentok/blob/main/frontend/src/lib/supabase/client.ts"
    click SupabaseAuth "https://github.com/dustland/agentok/blob/main/frontend/src/lib/supabase/auth.ts"
    click SupabaseMiddleware "https://github.com/dustland/agentok/blob/main/frontend/src/lib/supabase/middleware.ts"
    click SupabaseServer "https://github.com/dustland/agentok/blob/main/frontend/src/lib/supabase/server.ts"

    %% Styles
    classDef ui fill:#ccffcc,stroke:#008000,stroke-width:1px;
    classDef service fill:#cce5ff,stroke:#0044cc,stroke-width:1px;
    classDef api fill:#ffe5cc,stroke:#cc4400,stroke-width:1px;
    classDef data fill:#e5ccff,stroke:#8000cc,stroke-width:1px;
```
