# gbaeke/pocketflow architecture

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

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

## Overview

##### Project Type & Purpose
- Type: A hybrid CLI/library + microservice (Agent-to-Agent) application.
- Purpose: Generate structured tech documentation by orchestrating a serial workflow (validate → prepare → outline → research → write) using LLMs and web search.

##### Main Architectural Components
a. **Client Layer**
- CLI / direct Python invocation (`python -m tech_doc_generator` or library import)
- A2A Client (`src/tech_doc_generator/a2a/client.py`)
b. **Agent Server Layer**
- A2A Server (`src/tech_doc_generator/a2a/server.py`) running on Uvicorn (via `uvicorn` from requirements)
- Agent Executor (`src/tech_doc_generator/agent_executor.py`)
c. **Core Workflow Layer**
- Encapsulated Workflow Class (`TechnologyDocumentGenerator` in `src/tech_doc_generator/utils/tech_doc_generator.py`)
- Flow Orchestrator (`src/tech_doc_generator/flow.py`) implementing the serial execution pattern
- Nodes (`src/tech_doc_generator/nodes.py`):
- ValidateRequestNode
- PrepareDataNode
- CreateOutlineNode
- ResearchTechnologiesNode (AsyncParallelBatchNode)
- WriteDocumentNode
d. **Utility & Integration Layer**
- LLM Wrapper (`src/tech_doc_generator/utils/call_llm.py`) → OpenAI API
- Web Search Wrapper (`src/tech_doc_generator/utils/search_web.py`) → DuckDuckGo + BeautifulSoup4
- Validators (`src/tech_doc_generator/validators.py`)
- Constants & Exceptions (`constants.py`, `exceptions.py`)
e. **External Services**
- OpenAI API
- DuckDuckGo search engine (HTTP)
- Environment variables loader (`python-dotenv`)

##### Relationships & Data Flows
- **User Request** → CLI or A2A Client → **A2A Server** → Agent Executor
- Executor invokes **TechnologyDocumentGenerator.invoke()**
- **Serial Flow**:
1. ValidateRequestNode
2. PrepareDataNode
3. CreateOutlineNode → calls call_llm
4. ResearchTechnologiesNode → parallel calls to search_web and optionally call_llm
5. WriteDocumentNode → calls call_llm
- Final output → returned to client → printed or saved as Markdown

##### Architectural Patterns & Principles
- **Serial Workflow Pattern** for deterministic flow control
- **Async Parallel Batch** for research phase (improves throughput)
- **Agent-to-Agent (A2A)** for microservice decoupling
- **Encapsulation** via the `TechnologyDocumentGenerator` class
- **Retry/Timeout Configuration** per node (robustness)

- Clear labels: module path + responsibility (e.g., “CreateOutlineNode (calls OpenAI)”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI / Direct Python"]:::user
        A2AClient["A2A Client"]:::user
    end

    %% Agent Server Layer
    subgraph "Agent Server Layer"
        A2AServer["A2A Server"]:::microservice
        Executor["Agent Executor"]:::microservice
    end

    %% Core Workflow Layer
    subgraph "Core Workflow Layer"
        Generator["TechnologyDocumentGenerator"]:::core
        Flow["Flow Orchestrator"]:::core
        Validate["ValidateRequestNode"]:::core
        Prepare["PrepareDataNode"]:::core
        Outline["CreateOutlineNode"]:::core
        Research["ResearchTechnologiesNode"]:::core
        Write["WriteDocumentNode"]:::core
    end

    %% Utility & Integration Layer
    subgraph "Utility & Integration Layer"
        LLM["LLM Wrapper"]:::util
        Search["Web Search Wrapper"]:::util
        Validators["Validators"]:::util
        Constants["Constants"]:::util
        Exceptions["Exceptions"]:::util
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Duck["DuckDuckGo Search"]:::external
        Env["Env Loader"]:::external
    end

    %% Connections
    CLI -->|"direct call"| Generator
    CLI -->|"A2A request"| A2AClient
    A2AClient -->|"HTTP"| A2AServer
    A2AServer -->|"invoke"| Executor
    Executor -->|"calls invoke()"| Generator

    Generator --> Flow
    Flow --> Validate
    Validate --> Prepare
    Prepare --> Outline
    Outline --> Research
    Research --> Write
    Write --> CLI

    %% Node interactions
    Validate -->|"uses"| Validators
    Outline -->|"calls"| LLM
    Research -.parallel.-> Search
    Research -.optional call.-> LLM
    Write -->|"calls"| LLM

    %% Utilities to external
    LLM -->|"HTTP"| OpenAI
    Search -->|"HTTP"| Duck
    CLI -.uses.-> Env
    A2AServer -.uses.-> Env
    Executor -.uses.-> Env

    %% Click Events
    click CLI "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/__main__.py"
    click A2AClient "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/a2a/client.py"
    click A2AServer "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/a2a/server.py"
    click Executor "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/agent_executor.py"
    click Generator "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/utils/tech_doc_generator.py"
    click Flow "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/flow.py"
    click Validate "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/nodes.py"
    click Prepare "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/nodes.py"
    click Outline "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/nodes.py"
    click Research "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/nodes.py"
    click Write "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/nodes.py"
    click LLM "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/utils/call_llm.py"
    click Search "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/utils/search_web.py"
    click Validators "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/validators.py"
    click Constants "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/constants.py"
    click Exceptions "https://github.com/gbaeke/pocketflow/blob/main/src/tech_doc_generator/exceptions.py"

    %% Styles
    classDef user fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef microservice fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#ffa500,stroke:#333,stroke-width:1px
    classDef util fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
