# happyallday/pocketflow architecture

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

- Interactive diagram: https://gitdiagram.com/happyallday/pocketflow
- Repository: https://github.com/happyallday/pocketflow

## Overview

##### External dependencies (LLM vendors, databases, web frameworks)

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

##### Main components
- Core Library (pocketflow/__init__.py)
- Utility modules (docs/utility_function, .cursor/rules/*, utils/update_pocketflow_mdc.py)
- Design‐pattern docs (docs/design_pattern)
- Cookbook examples (cookbook/*)
- Tests (tests/*.py)
- Deployment/config (setup.py, requirements.txt in examples)

##### Relationships & data flows
- **Core Library** exports the Graph abstraction (Node, Flow classes).
– Indexed by setup.py for pip installation.
- **Design‐pattern & utility docs** reference Core Library APIs.
- **Cookbook examples** import pocketflow, define flows (flow.py), nodes (nodes.py), and launch via main.py.
– Some examples spin up a **CLI** (CLI‐HITL), **FastAPI** server (background tasks, WebSocket, HITL), **Streamlit** front‐end, **Gradio**, or interact with local files/databases.
– Each node typically calls an external service: LLM API (OpenAI/Anthropic, etc.), vector DB, Google Calendar, PDF vision, etc.
- **Tests** directly import pocketflow core to validate abstractions (async, batch, parallel flows, fallback, composition).

##### Call out architectural patterns
- **Graph** at heart: nodes represent LLM calls or data transforms; flows compose nodes.
- **Design patterns** layered on Graph: Agents (single & multi‐agent), Workflow, RAG, Map‐Reduce, Supervisor, Memory, Parallel & Batch processing.
- **Utility functions** pluggable: embedding, chunking, visualization, web search, text‐to‐speech.
- **Examples** showcase real‐world integrations:
– **Web frameworks**: FastAPI (SSE, WebSocket, background), Streamlit, Gradio
– **CLI** for HITL feedback
– **Databases**: SQLite for Text2SQL, ecommerce.db
– **Audio**: VAD, STT, TTS pipelines in voice‐chat

##### Technologies & frameworks
- Python 3.x
- LLM vendors via HTTP (OpenAI, self‐hosted)
- Web frameworks: FastAPI, Uvicorn, SSE, WebSocket
- Front‐ends: Streamlit, Gradio
- Databases: SQLite
- CI/test: pytest
- Packaging: setuptools

##### Detail & labeling

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Library
    subgraph "Core Library" 
        direction TB
        CoreInit["pocketflow/__init__.py"]:::core
        CoreGraph["Graph Abstraction\n(Node, Flow)"]:::core
        CoreCoreFiles["pocketflow/…"]:::core
    end

    %% Core Setup
    Setup["setup.py"]:::core

    CoreInit -->|defines| CoreGraph
    Setup -->|packages| CoreInit

    click CoreInit "https://github.com/happyallday/pocketflow/blob/main/pocketflow/__init__.py"
    click Setup "https://github.com/happyallday/pocketflow/blob/main/setup.py"

    %% Docs & Rules
    subgraph "Docs & Rules" 
        direction TB
        DPDocs["docs/design_pattern/…"]:::docs
        CAfork["docs/core_abstraction/…"]:::docs
        UFDocs["docs/utility_function/…"]:::docs
        CursorUtil[".cursor/rules/utility_function/…"]:::docs
        CursorCore[".cursor/rules/core_abstraction/…"]:::docs
        UtilScript["utils/update_pocketflow_mdc.py"]:::docs
    end

    DPDocs -->|references| CoreGraph
    CAfork -->|references| CoreGraph
    UFDocs -->|references| CoreGraph
    CursorUtil -->|defines rules| CoreGraph
    CursorCore -->|defines rules| CoreGraph
    UtilScript -->|updates docs| CoreGraph

    click DPDocs "https://github.com/happyallday/pocketflow/tree/main/docs/design_pattern/"
    click CAfork "https://github.com/happyallday/pocketflow/tree/main/docs/core_abstraction/"
    click UFDocs "https://github.com/happyallday/pocketflow/tree/main/docs/utility_function/"
    click CursorUtil "https://github.com/happyallday/pocketflow/tree/main/.cursor/rules/utility_function/"
    click CursorCore "https://github.com/happyallday/pocketflow/tree/main/.cursor/rules/core_abstraction/"
    click UtilScript "https://github.com/happyallday/pocketflow/blob/main/utils/update_pocketflow_mdc.py"

    %% Cookbook Examples
    subgraph "Cookbook Examples"
        direction TB
        subgraph "A2A" 
            direction TB
            A2AFlow["flow.py"]:::ex
            A2ANodes["nodes.py"]:::ex
            A2AMain["main.py"]:::ex
        end
        subgraph "FastAPI Background"
            direction TB
            FABFlow["flow.py"]:::ex
            FABNodes["nodes.py"]:::ex
            FABMain["main.py"]:::ex
        end
        subgraph "CLI HITL"
            direction TB
            CLIFlow["flow.py"]:::ex
            CLINodes["nodes.py"]:::ex
            CLIMain["main.py"]:::ex
        end
        subgraph "Streamlit FSM"
            direction TB
            STFlow["flow.py"]:::ex
            STApp["app.py"]:::ex
            STNodes["nodes.py"]:::ex
        end
        ReqFiles["requirements.txt"]:::ex
    end

    A2AFlow -->|imports| CoreInit
    A2ANodes -->|imports| CoreInit
    A2AMain -->|runs| A2AFlow

    FABFlow -->|imports| CoreInit
    FABNodes -->|imports| CoreInit
    FABMain -->|runs| FABFlow

    CLIFlow -->|imports| CoreInit
    CLINodes -->|imports| CoreInit
    CLIMain -->|runs| CLIFlow

    STFlow -->|imports| CoreInit
    STNodes -->|imports| CoreInit
    STApp -->|runs| STFlow

    click A2AFlow "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-a2a/flow.py"
    click A2ANodes "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-a2a/nodes.py"
    click A2AMain "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-a2a/main.py"
    click FABFlow "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-fastapi-background/flow.py"
    click FABNodes "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-fastapi-background/nodes.py"
    click FABMain "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-fastapi-background/main.py"
    click CLIFlow "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-cli-hitl/flow.py"
    click CLINodes "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-cli-hitl/nodes.py"
    click CLIMain "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-cli-hitl/main.py"
    click STFlow "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-streamlit-fsm/flow.py"
    click STApp "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-streamlit-fsm/app.py"
    click STNodes "https://github.com/happyallday/pocketflow/blob/main/cookbook/pocketflow-streamlit-fsm/nodes.py"
    click ReqFiles "https://github.com/happyallday/pocketflow/blob/main/cookbook/requirements.txt"

    %% Tests
    subgraph "Tests Suite"
        direction TB
        TestAsync["tests/test_async_flow.py"]:::test
        TestBatch["tests/test_batch_flow.py"]:::test
        TestOther["tests/*.py"]:::test
    end

    TestAsync -->|imports| CoreInit
    TestBatch -->|imports| CoreInit
    TestOther -->|imports| CoreInit

    click TestAsync "https://github.com/happyallday/pocketflow/blob/main/tests/test_async_flow.py"
    click TestBatch "https://github.com/happyallday/pocketflow/blob/main/tests/test_batch_flow.py"
    click TestOther "https://github.com/happyallday/pocketflow/tree/main/tests/"

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM Providers\n(OpenAI, Anthropic)"]:::cloud
        DB["SQLite DB"]:::db
        Calendar["Google Calendar API"]:::cloud
        PDF["PDF Vision API"]:::cloud
    end

    A2AMain -->|HTTP call| LLM
    FABMain -->|HTTP call| LLM
    CLIMain -->|HTTP call| LLM
    STApp -->|HTTP call| LLM

    A2AMain -->|DB query| DB
    FABMain -->|DB query| DB

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef docs fill:#fff3cd,stroke:#856404,color:#856404;
    classDef ex fill:#d4edda,stroke:#155724,color:#155724;
    classDef test fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cloud fill:#e0f7fa,stroke:#006064,color:#006064,stroke-dasharray: 5 5;
    classDef db fill:#f1f8e9,stroke:#33691e,color:#33691e;
```
