# dbos-inc/dbos-transact-py architecture

> Architecture diagram of the GitHub repository dbos-inc/dbos-transact-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dbos-inc/dbos-transact-py
- Repository: https://github.com/dbos-inc/dbos-transact-py

## Overview

##### Main Components

a) Core Components:
- Workflow Engine (Central Component)
- Step Executor
- Transaction Manager
- State Management System
- Database Connector (PostgreSQL)

b) Supporting Systems:
- FastAPI/Flask Integration Layer
- Kafka Integration
- Scheduler System
- Admin Server
- OpenTelemetry Tracer

##### Component Relationships

a) Primary Flow:
**User Application -> DBOS Decorator Layer -> Workflow Engine -> Step Executor -> Database**

b) Secondary Systems:
- Scheduler System -> Workflow Engine (for timed executions)
- Kafka Integration -> Workflow Engine (for event processing)
- Admin Server <- Database (for monitoring)
- OpenTelemetry Tracer (connected to all components)

##### Specific Implementation Details

- Blue rectangles: Core components
- Green rectangles: Integration layers (FastAPI/Flask)
- Yellow diamonds: External systems (PostgreSQL, Kafka)
- Purple rectangles: Monitoring components (Admin Server, OpenTelemetry)

##### Key Architectural Elements

Specific architectural patterns:
- Decorator Pattern (@DBOS.step(), @DBOS.workflow())
- Transaction Management System
- Event Processing System
- State Machine for Workflow Management

##### Component Details

Annotations for:
- Database Schema (from _schemas folder)
- Migration System (from _migrations folder)
- Configuration Management (dbos-config.yaml)
- Role-based Access Control (_roles.py)

##### Additional Notes

Callouts for:
- Configuration requirements
- Security boundaries
- Scaling points
- Failure recovery paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph User["User Application Layer"]
        UA[User Application]
    end

    subgraph Integration["Integration Layer"]
        FI["FastAPI Integration"]:::integration
        FL["Flask Integration"]:::integration
        KI["Kafka Integration"]:::integration
    end

    subgraph Core["Core Processing Layer"]
        WE["Workflow Engine"]:::core
        SE["Step Executor"]:::core
        TM["Transaction Manager"]:::core
        SMS["State Management System"]:::core
        QM["Queue Management"]:::queue
        RBAC["Role-based Access Control"]:::security
        CM["Configuration Management"]:::config
        CTX["Context Management"]:::core
        EH["Error Handler"]:::core
        SER["Serialization System"]:::core
    end

    subgraph Monitoring["Monitoring & Admin Layer"]
        AS["Admin Server"]:::monitoring
        OT["OpenTelemetry Tracer"]:::monitoring
    end

    subgraph External["External Systems"]
        DB[(PostgreSQL)]:::database
        KF[("Kafka")]:::messaging
        SCH["Scheduler"]:::scheduler
    end

    UA --> FI & FL & KI
    FI & FL & KI --> WE
    KI <--> KF
    WE --> SE
    SE --> TM
    TM --> SMS
    SMS --> DB
    SCH --> WE
    WE --> QM
    RBAC --> WE
    CM --> WE
    CTX --> WE
    EH --> WE
    SER --> WE
    DB <--> AS
    OT -.- WE & SE & TM & SMS & AS

    classDef core fill:#2374ab
    classDef integration fill:#57b8ff
    classDef database fill:#daa520
    classDef monitoring fill:#9370db
    classDef messaging fill:#ffd700
    classDef scheduler fill:#98fb98
    classDef queue fill:#ff69b4
    classDef security fill:#ff6b6b
    classDef config fill:#40e0d0

    click WE "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_core.py"
    click DB "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_app_db.py"
    click SMS "https://github.com/dbos-inc/dbos-transact-py/tree/main/dbos/_schemas/"
    click TM "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_recovery.py"
    click FI "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_fastapi.py"
    click FL "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_flask.py"
    click KI "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_kafka.py"
    click SCH "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_scheduler.py"
    click AS "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_admin_server.py"
    click OT "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_tracer.py"
    click QM "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_queue.py"
    click RBAC "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_roles.py"
    click CM "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_dbos_config.py"
    click CTX "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_context.py"
    click EH "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_error.py"
    click SER "https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/_serialization.py"
```
