# th2-net/run-one architecture

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

- Interactive diagram: https://gitdiagram.com/th2-net/run-one
- Repository: https://github.com/th2-net/run-one

## Overview

##### Project Type and Purpose
- This is a specialized file processing tool designed to parse matrix files, extract specific actions (like “send”, “receive”, “store”, etc.) and process them based on user-configured handlers.
- The README gives a clear configuration example that details how different actions map to handler classes, along with processor settings. This indicates that the tool is configurable and modular, aimed at flexibility in processing different types of matrix file inputs.

##### Analyzing the File Structure
- The main entry point is provided by “main.py” which likely initializes configuration reading (from config.yaml) and kicks off the processing pipeline.
- The “run_one” package is subdivided into three main folders:
- action_handlers: Contains different handler classes (e.g., TH2ActHandler, SleepHandler, TH2ActSSHHandler) and an abstract base for action handlers. This module encapsulates the logic for processing each type of action parsed from the matrix files.
- processors: Contains processor logic (with “th2_processor.py” as a key processor implementation) together with an abstract base, to handle overall processing and potentially orchestration of multiple actions.
- util: Provides configuration management (config.py) and general utilities (util.py) to support the modules.

##### System Components and Their Relationships
a. Main Components:
- Entry Point: main.py – responsible for initializing the system.
- Configuration: config.yaml (and related configuration management in run_one/util/config.py) – provides system parameters including file paths, action mapping, and processor configuration.
- File Input Module: Component that reads matrix files from a given directory or file. (This might be part of the parsing logic inside the main or within one of the processor modules.)
- Action Extraction Module: Parses matrix files and extracts individual actions along with metadata.
- Action Handlers: Located under run_one/action_handlers; includes specialized handler classes for different actions (e.g., TH2ActHandler, SleepHandler, etc.). These classes define how each specific action should be processed.
- Processors: Located under run_one/processors; encapsulate higher-level processing logic (for example, the “th2_processor” which likely coordinates processing based on the configuration details provided in the YAML file).
- Utility Components: run_one/util includes general helper functions that support configuration and core processing.
- CI/CD Components: GitHub workflows (for releases and snapshots) that automate packaging, testing, and deploying the tool.

b. Relationships & Interactions:
- The entry point (main.py) will first load configurations (from config.yaml and via the config utility) and then initialize the processor.
- The processor module will read the matrix file (or files), extract actions, and then delegate each action to its corresponding handler from the action_handlers module (based on the mapping given in the configuration).
- Each action handler processes a specific action (e.g., sending an action, checking, sleeping, storing, etc.), optionally interacting with other external services or protocols (e.g., SSH in TH2ActSSHHandler).
- Utilities support each module – e.g., handling config parsing or common error handling.
- Flows between these modules can be understood as a pipeline (or a sequence of function calls): Input Reading → Parsing/Extraction → Processing/Delegation → Handler Execution.

##### Architectural Patterns and Technologies Used
- The project design reflects a modular pattern: separation of concerns among configuration, processing logic, and action handling.
- It leverages extensibility via abstract classes (for both action handlers and processors) which encourages adding new types of actions or processors while reusing existing code.
- The use of a YAML configuration suggests the principles of external configuration and dependency injection in mapping actions to handlers.
- Dependency management and environment setup guidelines in the README hint at the use of Poetry and virtual environments, meaning that external Python libraries play important roles.

- Clear labels for each identified component (e.g., “main.py (Entry Point)”, “Configuration Loader”, “Matrix Parser”, “Action Handlers (TH2ActHandler, SleepHandler, etc.)”, “Processor (th2_processor)”).
- An auxiliary note for the CI/CD pipeline indicating automated release and test workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("main.py (Entry Point)"):::entry
    subgraph "Configuration"
        B("config.yaml"):::config
        C("run_one/util/config.py"):::config
    end
    subgraph "Processor Module"
        D("th2_processor"):::core
        R("Abstract Processor"):::core
    end
    E("Matrix File Input & Parser"):::core
    F("Action Extraction"):::core
    subgraph "Action Handlers"
        G("TH2ActHandler"):::handler
        H("SleepHandler"):::handler
        I("TH2ActSSHHandler"):::handler
        J("TH2Check1Handler"):::handler
        K("TH2EstoreHandler"):::handler
        L("Abstract Action Handler"):::handler
        M("Context"):::handler
    end
    N("Utility: util.py"):::util
    subgraph "CI/CD Pipeline"
        O("publish-release-canditate.yml"):::cicd
        P("publish-release.yml"):::cicd
        Q("publish-snapshot.yml"):::cicd
    end

    %% Core Process Flow
    A -->|"loads"| B
    A -->|"loads"| C
    B -->|"configures"| D
    C -->|"configures"| D
    D -->|"reads"| E
    E -->|"parses"| F
    F -->|"delegates"| G
    F -->|"delegates"| H
    F -->|"delegates"| I
    F -->|"delegates"| J
    F -->|"delegates"| K
    F -->|"delegates"| L
    F -->|"delegates"| M
    D -.->|"utilizes"| N
    D -.->|"inherits"| R

    %% CI/CD triggering deployment (auxiliary)
    O -->|"triggers"| A
    P -->|"triggers"| A
    Q -->|"triggers"| A

    %% Click Events
    click A "https://github.com/th2-net/run-one/blob/master/main.py"
    click B "https://github.com/th2-net/run-one/blob/master/config.yaml"
    click C "https://github.com/th2-net/run-one/blob/master/run_one/util/config.py"
    click D "https://github.com/th2-net/run-one/blob/master/run_one/processors/th2_processor.py"
    click R "https://github.com/th2-net/run-one/blob/master/run_one/processors/abstract_processor.py"
    click G "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/TH2ActHandler.py"
    click H "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/SleepHandler.py"
    click I "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/TH2ActSSHHandler.py"
    click J "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/TH2Check1Handler.py"
    click K "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/TH2EstoreHandler.py"
    click L "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/abstract_action_handler.py"
    click M "https://github.com/th2-net/run-one/blob/master/run_one/action_handlers/context.py"
    click N "https://github.com/th2-net/run-one/blob/master/run_one/util/util.py"
    click O "https://github.com/th2-net/run-one/blob/master/.github/workflows/publish-release-canditate.yml"
    click P "https://github.com/th2-net/run-one/blob/master/.github/workflows/publish-release.yml"
    click Q "https://github.com/th2-net/run-one/blob/master/.github/workflows/publish-snapshot.yml"

    %% Styles
    classDef entry fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef handler fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef util fill:#e0ccff,stroke:#333,stroke-width:2px;
    classDef cicd fill:#d9ead3,stroke:#333,stroke-width:2px;
```
