# whiteducksoftware/flock architecture

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

- Interactive diagram: https://gitdiagram.com/whiteducksoftware/flock
- Repository: https://github.com/whiteducksoftware/flock

## Overview

##### Principal components
- Flock Core Engine: At the center is the engine responsible for managing agents, their definitions, and the orchestration of workflows.
- Agent System: This encapsulates the “FlockAgent” entities along with their declarative input/output definition. Indicate that these agents can be dynamically chained (via the “hand_off” mechanism).
- Tools Integration: Represent the tools (e.g., web search, code evaluation, etc.) as a separate module that can be attached to agents. This module is plugged into the agent system (as seen in the agents’ 'tools' attribute).
- Logging & Telemetry: Include components for logging (with formatters, tracing, telemetry exporters like file and SQLite exporters) and monitoring integrations (such as Jaeger).
- CLI & Configuration: Represent the command-line interface layer (under src/flock/cli), configuration files (like .env_template and config.py), and external settings that allow users to launch agents and run examples.
- External Integrations: Illustrate integrations with external services (e.g., Temporal, DSPy, Litellm for LLM interaction, and even integrations such as Tavily for search services).

##### Establish relationships and data flows
- The CLI and configuration modules feed into the Flock Core Engine.
- The agents then communicate with one another either directly (through declared hand-offs) or via the workflow manager.
- The Workflow/Execution System (Temporal integrated) orchestrates the agent executions and ensures fault tolerance.

##### Architectural design notes
- That the system is highly modular – each subsystem (core, agents, evaluators, modules, routers, context, tools, logging) is loosely coupled and independently testable.
- Declarative programming paradigm: Agent definitions are lean (using clear type contracts via Pydantic) and self-contained.
- Use of Temporal for durable workflows, which is central for production-grade fault tolerance and error recovery.
- The tool integration is designed to be extendable with plugins (illustrate this by separate “tool” nodes that plug into the agent framework).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("CLI & Configuration"):::cli
    B("Flock Core Engine"):::core
    C("Agent System"):::agent
    D("Workflow/Execution System"):::workflow
    E("Tools Integration"):::tools
    F("Context & Serialization Modules"):::context
    G("Evaluation & Routing Subsystems"):::evalrouter
    H("Logging & Telemetry"):::logging
    I("External Integrations"):::external

    A -->|"feeds"| B
    B -->|"agent_instantiation"| C
    B -->|"schedules"| D
    D -->|"triggers"| C
    C -->|"hand_off"| C
    C -->|"invokes"| E
    F -->|"data_enrichment"| C
    B -->|"routing_decisions"| G
    G -->|"agent_routing"| C
    C -->|"logs"| H
    H -->|"monitoring_feedback"| B
    I -->|"external_service_calls"| B
    I -->|"workflow_integration"| D

    click A "https://github.com/whiteducksoftware/flock/tree/master/src/flock/cli/"
    click B "https://github.com/whiteducksoftware/flock/blob/master/src/flock/core/flock.py"
    click C "https://github.com/whiteducksoftware/flock/blob/master/src/flock/core/flock_agent.py"
    click D "https://github.com/whiteducksoftware/flock/tree/master/src/flock/workflow/"
    click E "https://github.com/whiteducksoftware/flock/tree/master/src/flock/core/tools/"
    click F "https://github.com/whiteducksoftware/flock/tree/master/src/flock/core/context/"
    click G "https://github.com/whiteducksoftware/flock/tree/master/src/flock/evaluators/"
    click H "https://github.com/whiteducksoftware/flock/tree/master/src/flock/core/logging/"
    click I "https://github.com/whiteducksoftware/flock/tree/master/src/flock/platform/"

    classDef cli fill:#f9e79f,stroke:#000,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#000,stroke-width:2px;
    classDef agent fill:#d5f5e3,stroke:#000,stroke-width:2px;
    classDef workflow fill:#fcf3cf,stroke:#000,stroke-width:2px;
    classDef tools fill:#f5cba7,stroke:#000,stroke-width:2px;
    classDef context fill:#d7bde2,stroke:#000,stroke-width:2px;
    classDef evalrouter fill:#f1948a,stroke:#000,stroke-width:2px;
    classDef logging fill:#aed6f1,stroke:#000,stroke-width:2px;
    classDef external fill:#a3e4d7,stroke:#000,stroke-width:2px;
```
