# manthanguptaa/water architecture

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

- Interactive diagram: https://gitdiagram.com/manthanguptaa/water
- Repository: https://github.com/manthanguptaa/water

## Overview

Overview
Water is a Python-based, framework-agnostic orchestration library that lets developers define, coordinate, and run complex multi-agent workflows. It exposes a clean Flow/Task API, plugs into any agent implementation (e.g., LangChain, CrewAI, custom agents), and even spins up a lightweight FastAPI server as a playground for your flows.

##### Project type and purpose
- Type: Open-source orchestration framework / library with an optional service component (FastAPI playground).
- Purpose: Provide a generic coordination layer for multi-agent workflows, decoupling orchestration logic from any specific agent framework.

##### File structure
- Top-level
- pyproject.toml: build and dependencies config
- README.md, LICENSE: project metadata
- cookbook/: example scripts showing sequential, parallel, branched, loop, and custom flows
- tests/: unit tests for core flow logic
- water/ (core package)
- config.py: global settings, defaults, environment overrides
- context.py: runtime context to carry state across tasks
- exceptions.py: framework-specific error types
- execution_engine.py: the engine that schedules, dispatches, and monitors task runs
- flow.py: Flow class and chainable builder methods (.then(), .parallel(), etc.)
- task.py: Task abstraction and factory (`create_task`)
- types.py: shared type aliases and Pydantic schemas
- server.py: FastAPI app wrapping Flow definitions for a web playground

##### Insights from README
- Key features: framework-agnostic, flexible workflows, built-in FastAPI playground
- Tech stack: Python ≥3.8, AsyncIO, Pydantic for schemas, FastAPI for the server
- Usage pattern: define Pydantic input/output models → create tasks via `create_task` → chain tasks in a Flow → run or register flows → optional web UI

##### Diagramming the system
a. Main components to represent
- User application / client code (defines Flows and Tasks)
- Flow API (flow.py)
- Task factory (task.py)
- Execution Engine (execution_engine.py)
- Runtime Context (context.py)
- Configuration layer (config.py)
- Exception handling (exceptions.py)
- Types & Schemas (types.py)
- External Agent Frameworks (e.g., LangChain, CrewAI, custom adapters)
- Optional FastAPI Server (server.py)
b. Relationships & interactions
1. Client code → calls Flow builder → Flow object
2. Flow.run() / server endpoint → invokes Execution Engine
3. Execution Engine → initializes Context → iterates tasks
4. For each Task: Execution Engine calls Task.execute(), which in turn invokes the underlying agent via an adapter
5. Task results update Context → feed next task(s)
6. Final result returned to client or HTTP response
c. Architectural patterns & principles
- Builder/Fluent API for constructing Flows
- Adapter pattern for plugging in arbitrary agent frameworks
- Pipeline pattern (sequential, parallel, branched, loop flows)
- Single Responsibility: separate modules for config, context, execution, server
d. Key technologies & libraries
- AsyncIO (asynchronous execution)
- Pydantic (input/output schemas)
- FastAPI (playground server)
- Standard Python typing for pluggable agent adapters

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Examples
    Client["Client Application<br/>(Defines Flows & Tasks)"]:::client
    ExampleFlows["Example Workflows<br/>(cookbook/)"]:::example

    %% Core Library Modules
    subgraph "Core Library"
        Flow["Flow API<br/>(water/flow.py)"]:::core
        Task["Task Factory<br/>(water/task.py)"]:::core
        Engine["Execution Engine<br/>(water/execution_engine.py)"]:::core
        Context["Runtime Context<br/>(water/context.py)"]:::core
        Config["Configuration Layer<br/>(water/config.py)"]:::core
        Exceptions["Exception Handling<br/>(water/exceptions.py)"]:::core
        Types["Types & Schemas<br/>(water/types.py)"]:::core
    end

    %% Server and Tests
    Server["FastAPI Playground Server<br/>(water/server.py)"]:::server
    TestFlow["Core Flow Tests<br/>(tests/test_flow.py)"]:::test

    %% External Frameworks
    AgentFrameworks["External Agent Frameworks<br/>(LangChain, CrewAI, Custom)"]:::external

    %% Relationships
    Client -->|defines flows/tasks| Flow
    ExampleFlows -->|provides usage examples| Flow
    Server -->|registers & runs flows| Flow
    Flow -->|builds & configures| Engine
    Engine -->|initializes| Context
    Engine -->|loads settings from| Config
    Engine -->|handles errors via| Exceptions
    Flow -->|uses schemas| Types
    Engine -->|executes via| Task
    Task -->|invokes| AgentFrameworks
    Task -->|updates| Context
    Engine -->|returns results to| Client
    Engine -->|sends HTTP responses to| Server
    TestFlow -->|tests core API| Flow

    %% Click Events
    click Flow "https://github.com/manthanguptaa/water/blob/main/water/flow.py"
    click Task "https://github.com/manthanguptaa/water/blob/main/water/task.py"
    click Engine "https://github.com/manthanguptaa/water/blob/main/water/execution_engine.py"
    click Context "https://github.com/manthanguptaa/water/blob/main/water/context.py"
    click Config "https://github.com/manthanguptaa/water/blob/main/water/config.py"
    click Exceptions "https://github.com/manthanguptaa/water/blob/main/water/exceptions.py"
    click Types "https://github.com/manthanguptaa/water/blob/main/water/types.py"
    click Server "https://github.com/manthanguptaa/water/blob/main/water/server.py"
    click ExampleFlows "https://github.com/manthanguptaa/water/tree/main/cookbook/"
    click TestFlow "https://github.com/manthanguptaa/water/blob/main/tests/test_flow.py"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    classDef server fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef example fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef client fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
```
