# jsv4/botsonrails architecture

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

- Interactive diagram: https://gitdiagram.com/jsv4/botsonrails
- Repository: https://github.com/jsv4/botsonrails

## Overview

##### Main Components

a) Core Framework Components:
- Node System (from nodes.py)
- Rails System (from rails.py)
- Storage Layer (from stores.py)
- Type System (from types.py)
- Execution Engine

b) Integration Points:
- LLM Services
- Human Interface Points
- External Systems Connection Points

##### Key Relationships to Highlight

- Data flow between nodes
- Control flow in the workflow tree
- Type validation paths
- State persistence flows
- Human interaction points

##### Specific Implementation Details

- Tree-based execution model
- Type checking system
- Visualization capabilities (Graphviz integration)
- State persistence mechanism
- Human-in-the-loop integration points

##### Technical Details

Annotations for:
- Python type hints system integration
- Graphviz visualization capabilities
- State persistence mechanisms
- Workflow validation rules
- Error handling paths

##### Implementation Notes

Callouts for:
- Required dependencies (Graphviz)
- Integration patterns
- Extension points
- Common implementation patterns

##### Resumable execution

Keep the abstraction level high enough to show the overall architecture but detailed enough to illustrate the unique features of BotsOnRails, particularly its tree-based workflow structure and human-in-the-loop capabilities.

Remember to include example flows from the provided example applications to demonstrate real-world usage patterns and implementation scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style Definitions
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:2px
    classDef human fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef state fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef example fill:#FFB6C1,stroke:#333,stroke-width:2px

    %% Client Applications Layer
    subgraph Applications
        CM["Content Moderation"]:::example
        DP["Document Processing"]:::example
        LI["LLM Interface"]:::example
    end
    click CM "https://github.com/JSv4/BotsOnRails/blob/main/docs/examples/content_moderation/main.py"
    click LI "https://github.com/JSv4/BotsOnRails/blob/main/docs/examples/llamaindex/main.py"

    %% Core Framework Layer
    subgraph CoreFramework
        NS[("Node System")]:::core
        RS[("Rails System")]:::core
        TS[("Type System")]:::core
        WE["Workflow Engine"]:::core
        SM["State Management"]:::core
        RE["Resumable Execution"]:::core
        VIS["Visualization System"]:::core
        TC["Type Checking"]:::core
        RT["Router"]:::core
        CD["Cycle Detection"]:::core
    end
    click NS "https://github.com/JSv4/BotsOnRails/blob/main/BotsOnRails/nodes.py"
    click RS "https://github.com/JSv4/BotsOnRails/blob/main/BotsOnRails/rails.py"
    click TS "https://github.com/JSv4/BotsOnRails/blob/main/BotsOnRails/types.py"
    click WE "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_tree_execution.py"
    click VIS "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_tree_visualizations.py"
    click SM "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_resumable_execution.py"
    click TC "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_function_type_checking.py"
    click RT "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_node_routers.py"
    click CD "https://github.com/JSv4/BotsOnRails/blob/main/tests/test_cycle_validations.py"

    %% Integration Layer
    subgraph IntegrationLayer
        LLMC["LLM Connectors"]:::integration
        HIP["Human Interface Points"]:::human
        SS["Storage Systems"]:::integration
        ESI["External Service Integration"]:::external
    end
    click SS "https://github.com/JSv4/BotsOnRails/blob/main/BotsOnRails/stores.py"
    click HIP "https://github.com/JSv4/BotsOnRails/blob/main/docs/examples/marvin/agent.py"

    %% Relationships
    CM --> NS
    DP --> NS
    LI --> NS
    
    NS --> RS
    NS --> TS
    NS --> WE
    
    WE --> SM
    WE --> RE
    WE --> VIS
    
    TS --> TC
    RS --> RT
    RT --> CD
    
    WE --> LLMC
    WE --> HIP
    WE --> SS
    WE --> ESI

    %% Legend
    subgraph Legend
        L1[("Core Component")]:::core
        L2["Integration Point"]:::integration
        L3["Human Interaction"]:::human
        L4["External Service"]:::external
        L5["State Management"]:::state
        L6["Example Application"]:::example
    end
```
