# orchestron-orchestrator/orchestron architecture

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

- Interactive diagram: https://gitdiagram.com/orchestron-orchestrator/orchestron
- Repository: https://github.com/orchestron-orchestrator/orchestron

## Overview

##### Project type and purpose
- Orchestron is a command-line platform/library (written in the Acton language) for building reactive, model-driven network orchestration systems.
- It ingests configuration events (northbound APIs) and streaming telemetry, applies layered “transforms” built from static types (derived from YANG models), and emits automation actions or generated artifacts (e.g., device configs, code stubs).

##### Top-level file structure & architectural hints
- Root:
- Acton.toml, build.act.json, Makefile → build system & CLI packaging
- .github/workflows → CI for tests & compliance
- docs/ → user/developer documentation & assets
- gen_dmc/ → a standalone code-generation plugin (YANG→DMC) with its own build
- src/
- orchestron.act → CLI launcher & entry point
- src/orchestron/ → core modules (device models, transform runners, YANG type loader, TTT transform & generator)
- top-level test_*.act → unit tests for core transform layers
- test/golden/ → expected outputs for integration/golden-file tests

##### Key README insights
- Emphasis on “transforms” as first-class, layered, declarative blocks
- Reactive event-driven core (subscriptions on telemetry & config changes)
- Use of static types derived from YANG to catch errors at compile time

##### Main components
- Northbound API (e.g., REST/gRPC config changes)
- Streaming telemetry subscriber
- Parses CLI args, loads configuration
- Dispatches incoming events to transform layers
- Core transform runner (ttt.act, ttt_gen.act)
- Device model loader (device.act, device_meta_config.act)
- YANG-type generator (yang.act)
- Plugin sub-folder gen_dmc (YANG→DMC codegen)
- Generated Acton types from YANG (oyang.act)
- Device configuration commands
- Generated code/artifacts (e.g., DMC stubs)
- Unit tests (test_*.act)
- Golden-file tests (test/golden/)
- GitHub workflows

##### Relationships & Data flow
- Event Bus → Transform Engine → individual Transform Modules
- Transform Modules read Data Models → emit Outputs
- Plugin (gen_dmc) is loaded by the Transform Engine via a module boundary
- Tests invoke the CLI/Engine with sample inputs and compare against golden outputs
- CI orchestrates build → tests → compliance

##### Architectural patterns & principles
- Pipeline of pure, layered transforms (functional-style)
- Static typing “left shifted” via code generation from YANG
- Modular plugin architecture (core + gen_dmc)
- Reactive event bus separating sources from processing

##### Technologies & frameworks
- Acton language & its build system (Acton.toml, build.act.json)
- GitHub Actions for CI & REUSE compliance
- YANG models for type generation
- Makefile as developer convenience

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Event Sources"
        API["Northbound API"]:::event
        Telemetry["Streaming Telemetry"]:::event
    end

    CLI["Orchestron CLI/Launcher\n(src/orchestron.act)"]:::core
    click CLI "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron.act"

    API --> CLI
    Telemetry --> CLI

    Reactor["Event Bus / Reactor Core"]:::core
    CLI --> Reactor

    subgraph "Core Transforms (src/orchestron)"
        TTT["ttt.act\n(Core Transform Runner)"]:::core
        TTG["ttt_gen.act\n(Transform Generator)"]:::core
        DeviceLoader["device.act\n(Device Model Loader)"]:::core
        DeviceMeta["device_meta_config.act"]:::core
        YANGGen["yang.act\n(YANG Type Generator)"]:::core
    end

    click TTT "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron/ttt.act"
    click TTG "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron/ttt_gen.act"
    click DeviceLoader "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron/device.act"
    click DeviceMeta "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron/device_meta_config.act"
    click YANGGen "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/orchestron/yang.act"

    Reactor --> TTT
    Reactor --> TTG
    Reactor --> DeviceLoader
    Reactor --> DeviceMeta
    Reactor --> YANGGen

    subgraph "Data Models & Types"
        Oyang["oyang.act\n(Generated Acton Types)"]:::data
    end

    click Oyang "https://github.com/orchestron-orchestrator/orchestron/blob/main/gen_dmc/src/oyang.act"

    YANGGen --> Oyang
    DeviceLoader --> Oyang

    subgraph "Plugin: gen_dmc"
        Dmc["gen_dmc.act\n(YANG→DMC CodeGen)"]:::plugin
    end

    click Dmc "https://github.com/orchestron-orchestrator/orchestron/blob/main/gen_dmc/src/gen_dmc.act"

    Reactor --> Dmc
    Dmc -->|"uses types"| Oyang
    Dmc -->|"emits code"| OutputCode

    subgraph "Outputs"
        DevCfg["Device Config Commands"]:::output
        OutputCode["Generated Code/Artifacts"]:::output
    end

    TTT --> DevCfg
    TTG --> OutputCode
    DeviceLoader --> DevCfg

    subgraph "Build & CI/Test"
        Build["Acton.toml\nbuild.act.json\nMakefile"]:::infra
        CI["GitHub Actions\n(.github/workflows)"]:::infra
        UnitTests["Unit Tests\n(src/test_*.act)"]:::infra
        Golden["Golden Tests\ntest/golden/"]:::infra
        Docs["docs/"]:::infra
    end

    click Build "https://github.com/orchestron-orchestrator/orchestron/blob/main/Acton.toml"
    click Build "https://github.com/orchestron-orchestrator/orchestron/blob/main/build.act.json"
    click Build "https://github.com/orchestron-orchestrator/orchestron/tree/main/Makefile"
    click CI "https://github.com/orchestron-orchestrator/orchestron/blob/main/.github/workflows/test.yml"
    click CI "https://github.com/orchestron-orchestrator/orchestron/blob/main/.github/workflows/reuse-compliance.yml"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_callbacks.act"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_container.act"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_gen.act"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_layers.act"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_list.act"
    click UnitTests "https://github.com/orchestron-orchestrator/orchestron/blob/main/src/test_ttt_transform.act"
    click Golden "https://github.com/orchestron-orchestrator/orchestron/tree/main/test/golden/"
    click Docs "https://github.com/orchestron-orchestrator/orchestron/tree/main/docs/"

    CLI --> Build
    Build --> CI
    CI --> UnitTests
    CI --> Golden
    CI --> Docs
    UnitTests -->|"validate transforms"| TTT
    Golden -->|"integration validation"| OutputCode

    classDef event fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef core fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef plugin fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef data fill:#b3e5fc,stroke:#01579b,color:#01579b
    classDef output fill:#ffccbc,stroke:#bf360c,color:#bf360c
    classDef infra fill:#e0e0e0,stroke:#424242,color:#424242
```
