# prefecthq/prefect architecture

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

- Interactive diagram: https://gitdiagram.com/prefecthq/prefect
- Repository: https://github.com/prefecthq/prefect
- Video tour (about a minute): https://gitdiagram.com/prefecthq/prefect/video

## Overview

Prefect is a Python workflow-orchestration framework. A user decorates Python functions as flows and tasks, runs the flow, and can deploy it for scheduled or event-triggered execution; run activity is observable through a self-hosted server or Prefect Cloud. The graph includes execution, orchestration access, deployment, and major supporting capabilities. Several relationships come from the README or SOURCE INDEX references rather than inspected implementations, so uncertain UI and external-service links are marked dashed.

Main entry points: [`src/prefect/flow_engine.py`](https://github.com/prefecthq/prefect/blob/main/src/prefect/flow_engine.py) (Flow runtime), [`src/prefect/task_engine.py`](https://github.com/prefecthq/prefect/blob/main/src/prefect/task_engine.py) (Task runtime), [`src/prefect/flows.py`](https://github.com/prefecthq/prefect/blob/main/src/prefect/flows.py) (Flow definitions), [`src/prefect/client/orchestration/__init__.py`](https://github.com/prefecthq/prefect/blob/main/src/prefect/client/orchestration/__init__.py) (Orchestration client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Workflow authoring"]
  node_flows["Flow definitions<br/>[flows.py]"]
  node_tasks["Task definitions<br/>[tasks.py]"]
end

subgraph group_execution["Run execution"]
  node_flow_engine["Flow runtime<br/>[flow_engine.py]"]
  node_task_engine["Task runtime<br/>[task_engine.py]"]
  node_context["Run context<br/>[context.py]"]
  node_states["Run states<br/>[states.py]"]
  node_pydantic["Model utilities<br/>[pydantic.py]"]
end

subgraph group_orchestration["Orchestration services"]
  node_client["Orchestration client<br/>[__init__.py]"]
  node_server["Prefect server<br/>[server.py]"]
  node_database[("Server database")]
  node_deployments["Deployment tools"]
end

subgraph group_capabilities["Workflow capabilities"]
  node_blocks["Blocks and storage<br/>[core.py]"]
  node_filesystems["File storage<br/>[filesystems.py]"]
  node_results["Results and caching<br/>[results.py]"]
  node_concurrency["Concurrency limits<br/>[asyncio.py]"]
  node_automations["Event automations<br/>[automations.py]"]
  node_events["Event processing<br/>[pipeline.py]"]
  node_logging["Run logging<br/>[loggers.py]"]
  node_integrations["External integrations"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands"]
  node_ui["Web UI"]
end

node_user(("Workflow author"))

node_user -->|"defines flow"| node_flows
node_user -->|"defines tasks"| node_tasks
node_flows -.->|"runs flow"| node_flow_engine
node_flow_engine -.->|"runs tasks"| node_task_engine
node_flow_engine -->|"uses context"| node_context
node_task_engine -->|"uses context"| node_context
node_flow_engine -->|"calls API"| node_client
node_task_engine -->|"calls API"| node_client
node_client -.->|"sends requests"| node_server
node_server -.->|"persists data"| node_database
node_user -->|"configures deployment"| node_deployments
node_deployments -.->|"deploys flow"| node_flows
node_user -.->|"runs commands"| node_cli
node_user -->|"monitors runs"| node_ui
node_ui -.->|"requests data"| node_server
node_flow_engine -.->|"updates state"| node_states
node_task_engine -->|"acquires slots"| node_concurrency
node_flow_engine -.->|"stores results"| node_results
node_blocks -->|"provides storage"| node_filesystems
node_flow_engine -.->|"emits run logs"| node_logging
node_automations -.->|"reacts to events"| node_events
node_integrations -.->|"extends workflows"| node_flows
node_pydantic -->|"supports models"| node_blocks

click node_flows "https://github.com/prefecthq/prefect/blob/main/src/prefect/flows.py"
click node_tasks "https://github.com/prefecthq/prefect/blob/main/src/prefect/tasks.py"
click node_flow_engine "https://github.com/prefecthq/prefect/blob/main/src/prefect/flow_engine.py"
click node_task_engine "https://github.com/prefecthq/prefect/blob/main/src/prefect/task_engine.py"
click node_context "https://github.com/prefecthq/prefect/blob/main/src/prefect/context.py"
click node_states "https://github.com/prefecthq/prefect/blob/main/src/prefect/states.py"
click node_client "https://github.com/prefecthq/prefect/blob/main/src/prefect/client/orchestration/__init__.py"
click node_server "https://github.com/prefecthq/prefect/blob/main/src/prefect/server/api/server.py"
click node_database "https://github.com/prefecthq/prefect/tree/main/src/prefect/server/database"
click node_deployments "https://github.com/prefecthq/prefect/tree/main/src/prefect/cli/deploy"
click node_cli "https://github.com/prefecthq/prefect/tree/main/src/prefect/cli"
click node_ui "https://github.com/prefecthq/prefect/tree/main/ui-v2/src"
click node_blocks "https://github.com/prefecthq/prefect/blob/main/src/prefect/blocks/core.py"
click node_filesystems "https://github.com/prefecthq/prefect/blob/main/src/prefect/filesystems.py"
click node_results "https://github.com/prefecthq/prefect/blob/main/src/prefect/results.py"
click node_concurrency "https://github.com/prefecthq/prefect/blob/main/src/prefect/concurrency/asyncio.py"
click node_automations "https://github.com/prefecthq/prefect/blob/main/src/prefect/automations.py"
click node_events "https://github.com/prefecthq/prefect/blob/main/src/prefect/server/events/pipeline.py"
click node_logging "https://github.com/prefecthq/prefect/blob/main/src/prefect/logging/loggers.py"
click node_integrations "https://github.com/prefecthq/prefect/tree/main/src/integrations"
click node_pydantic "https://github.com/prefecthq/prefect/blob/main/src/prefect/utilities/pydantic.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flows,node_tasks toneBlue
class node_flow_engine,node_task_engine,node_context,node_states,node_pydantic toneAmber
class node_client,node_server,node_database,node_deployments toneMint
class node_blocks,node_filesystems,node_results,node_concurrency,node_automations,node_events,node_logging,node_integrations toneRose
class node_cli,node_ui,node_user toneIndigo
```

## Components

### Workflow authoring

- [Flow definitions](https://github.com/prefecthq/prefect/blob/main/src/prefect/flows.py): `src/prefect/flows.py`
- [Task definitions](https://github.com/prefecthq/prefect/blob/main/src/prefect/tasks.py): `src/prefect/tasks.py`

### Run execution

- [Flow runtime](https://github.com/prefecthq/prefect/blob/main/src/prefect/flow_engine.py): `src/prefect/flow_engine.py`
- [Task runtime](https://github.com/prefecthq/prefect/blob/main/src/prefect/task_engine.py): `src/prefect/task_engine.py`
- [Run context](https://github.com/prefecthq/prefect/blob/main/src/prefect/context.py): `src/prefect/context.py`
- [Run states](https://github.com/prefecthq/prefect/blob/main/src/prefect/states.py): `src/prefect/states.py`
- [Model utilities](https://github.com/prefecthq/prefect/blob/main/src/prefect/utilities/pydantic.py): `src/prefect/utilities/pydantic.py`

### Orchestration services

- [Orchestration client](https://github.com/prefecthq/prefect/blob/main/src/prefect/client/orchestration/__init__.py): `src/prefect/client/orchestration/__init__.py`
- [Prefect server](https://github.com/prefecthq/prefect/blob/main/src/prefect/server/api/server.py): `src/prefect/server/api/server.py`
- [Server database](https://github.com/prefecthq/prefect/tree/main/src/prefect/server/database): `src/prefect/server/database`
- [Deployment tools](https://github.com/prefecthq/prefect/tree/main/src/prefect/cli/deploy): `src/prefect/cli/deploy`

### Workflow capabilities

- [Blocks and storage](https://github.com/prefecthq/prefect/blob/main/src/prefect/blocks/core.py): `src/prefect/blocks/core.py`
- [File storage](https://github.com/prefecthq/prefect/blob/main/src/prefect/filesystems.py): `src/prefect/filesystems.py`
- [Results and caching](https://github.com/prefecthq/prefect/blob/main/src/prefect/results.py): `src/prefect/results.py`
- [Concurrency limits](https://github.com/prefecthq/prefect/blob/main/src/prefect/concurrency/asyncio.py): `src/prefect/concurrency/asyncio.py`
- [Event automations](https://github.com/prefecthq/prefect/blob/main/src/prefect/automations.py): `src/prefect/automations.py`
- [Event processing](https://github.com/prefecthq/prefect/blob/main/src/prefect/server/events/pipeline.py): `src/prefect/server/events/pipeline.py`
- [Run logging](https://github.com/prefecthq/prefect/blob/main/src/prefect/logging/loggers.py): `src/prefect/logging/loggers.py`
- [External integrations](https://github.com/prefecthq/prefect/tree/main/src/integrations): `src/integrations`

### User interfaces

- [CLI commands](https://github.com/prefecthq/prefect/tree/main/src/prefect/cli): `src/prefect/cli`
- [Web UI](https://github.com/prefecthq/prefect/tree/main/ui-v2/src): `ui-v2/src`

### Other components

- **Workflow author**

## Connections

- Workflow author → Flow definitions: defines flow (evidence: `README.md`)
- Workflow author → Task definitions: defines tasks (evidence: `README.md`)
- Flow definitions → Flow runtime: runs flow (evidence: `src/prefect/flow_engine.py`)
- Flow runtime → Task runtime: runs tasks
- Flow runtime → Run context: uses context (evidence: `src/prefect/flow_engine.py`)
- Task runtime → Run context: uses context (evidence: `src/prefect/task_engine.py`)
- Flow runtime → Orchestration client: calls API (evidence: `src/prefect/flow_engine.py`)
- Task runtime → Orchestration client: calls API (evidence: `src/prefect/task_engine.py`)
- Orchestration client → Prefect server: sends requests (evidence: `src/prefect/client/orchestration/__init__.py`)
- Prefect server → Server database: persists data
- Workflow author → Deployment tools: configures deployment (evidence: `README.md`)
- Deployment tools → Flow definitions: deploys flow
- Workflow author → CLI commands: runs commands
- Workflow author → Web UI: monitors runs (evidence: `README.md`)
- Web UI → Prefect server: requests data
- Flow runtime → Run states: updates state (evidence: `src/prefect/flow_engine.py`)
- Task runtime → Concurrency limits: acquires slots (evidence: `src/prefect/task_engine.py`)
- Flow runtime → Results and caching: stores results (evidence: `src/prefect/flow_engine.py`)
- Blocks and storage → File storage: provides storage (evidence: `src/prefect/filesystems.py`)
- Flow runtime → Run logging: emits run logs (evidence: `src/prefect/flow_engine.py`)
- Event automations → Event processing: reacts to events
- External integrations → Flow definitions: extends workflows (evidence: `README.md`)
- Model utilities → Blocks and storage: supports models
