# positronic-robotics/configuronic architecture

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

- Interactive diagram: https://gitdiagram.com/positronic-robotics/configuronic
- Repository: https://github.com/positronic-robotics/configuronic

## Overview

##### Project Type and Purpose
- Type: A Python “Configuration-as-Code” library (not a web app or full‐stack system)
- Purpose: Provide a minimal API (`Config` class + `@config` decorator) for defining, overriding, and instantiating hierarchical configs, plus automatic CLI generation via Python Fire.

##### File Structure
- Top‐level:
– configuronic/ (core package)
· __init__.py – public API (`Config`, `config` decorator, `cli`)
· config.py – implementation of `Config`, override/instantiate, import resolution
– examples/ – demonstration scripts
– tests/ – unit tests & support packages
– . github/workflows – CI for tests & releases
– pyproject.toml – build & dependency config
- Patterns: Single‐package library, CLI entry‐points, test harness, no external runtime services.

##### Extract Additional Insights from README
- Architecture is centered on two main operations: `override()` and `instantiate()`.
- Relative vs. absolute import resolution engine lives in the same package.
- CLI generation is delegated to `python-fire` under the hood.
- Examples illustrate how user‐scripts import `cfn.config`, define `@cfn.config` functions, then call `cfn.cli()`.

##### Main Components & Relationships
a. Components:
1. User Script (example or application importing configuronic)
2. CLI Layer (Python Fire wrapper inside `cli()` function)
3. Config Core (Config class + decorator + import‐resolution engine)
4. Python Runtime (executes decorated functions, resolves objects)
5. External Libraries (torch, transformers, hardware drivers) – optional at runtime
6. CI/CD (GitHub Actions workflows for tests & releases)
7. Tests & Examples (validate core logic and demonstrate usage)
b. Interactions:
– User invokes script → CLI Layer parses arguments → populates a `Config` object tree
– Config Core resolves imports (absolute `@` and relative `.` syntax)
– CLI calls `instantiate()`, which executes the underlying function(s) in Python Runtime
– Tests import Config Core directly to validate functionality
– CI/CD triggers tests, packages and publishes to PyPI
c. Architectural Patterns:
– Functional wrapper pattern (similar to `functools.partial`)
– Decorator pattern for registering user functions as `Config` objects
– Dependency injection via hierarchical configs and overrides
– Single‐package library with clear separation between core logic and CLI integration
d. Key Technologies:
– Python 3.10+
– Python Fire for CLI
– Standard library only for core; optional third-party imports inside user functions
– Pytest for tests
– GitHub Actions for CI/CD

##### Essential Details to Capture
- The two‐phase operation of `Config` (build vs. instantiate)
- Decorator registration in `__init__.py`
- Import resolution engine (absolute `@` vs. relative `.`)
- CLI integration hook (`cli()` uses Python Fire)
- Test structure under tests/ for validating CLI, Config, IPython integration
- CI workflows under .github/workflows

[ User Script (orange) ]
|
v
[ CLI Layer (blue) ] ---(parses args)---> [ Config Core (green): Config class + import resolution ]
|                                                         ^
|--(invokes instantiate())---> [ Python Runtime (rounded) ]
|      ^
v      |
[ User functions decorated with @cfn.config ]

Supporting Infrastructure (gray):
[ Tests Folder ] <--- run by --- [ CI/CD Workflows ] --- publish ---> [ PyPI ]

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Scripts"
        direction TB
        ExamplesInit["examples/__init__.py"]:::user
        UserScript["examples/basic.py"]:::user
    end

    subgraph "CLI Layer"
        direction TB
        CLI["CLI Layer (cli())"]:::cli
        PublicAPI["Public API (Config, @config, cli)"]:::cli
    end

    subgraph "Config Core"
        direction TB
        ConfigCore["configuronic/config.py\nConfig class, override, import resolution"]:::core
    end

    Runtime["Python Runtime"]:::runtime
    Decorated["User functions decorated with @config"]:::core

    subgraph "Supporting Infrastructure"
        direction TB
        subgraph Tests
            direction TB
            TestCLI["tests/test_cli.py"]:::infra
            TestConfig["tests/test_config.py"]:::infra
            TestIPython["tests/test_ipython.py"]:::infra
            SupportPkg["tests/support_package/"]:::infra
        end
        subgraph "CI/CD Workflows"
            direction TB
            TestWF[".github/workflows/test.yml"]:::infra
            ReleaseWF[".github/workflows/release.yml"]:::infra
            PyPI["PyPI"]:::infra
        end
        Build["pyproject.toml"]:::infra
        Meta["README.md"]:::infra
        License["LICENSE.md"]:::infra
    end

    ExamplesInit --> UserScript
    UserScript --> CLI
    CLI -->|"parses args & builds config tree"| ConfigCore
    CLI -->|"invokes instantiate()"| Runtime
    ConfigCore -->|"resolve imports & override"| Runtime
    Runtime -->|"executes decorated functions"| Decorated
    TestWF --> TestCLI
    TestWF --> TestConfig
    TestWF --> TestIPython
    ReleaseWF --> PyPI

    click ExamplesInit "https://github.com/positronic-robotics/configuronic/blob/main/examples/__init__.py"
    click UserScript "https://github.com/positronic-robotics/configuronic/blob/main/examples/basic.py"
    click CLI "https://github.com/positronic-robotics/configuronic/blob/main/configuronic/__init__.py"
    click PublicAPI "https://github.com/positronic-robotics/configuronic/blob/main/configuronic/__init__.py"
    click ConfigCore "https://github.com/positronic-robotics/configuronic/blob/main/configuronic/config.py"
    click TestCLI "https://github.com/positronic-robotics/configuronic/blob/main/tests/test_cli.py"
    click TestConfig "https://github.com/positronic-robotics/configuronic/blob/main/tests/test_config.py"
    click TestIPython "https://github.com/positronic-robotics/configuronic/blob/main/tests/test_ipython.py"
    click SupportPkg "https://github.com/positronic-robotics/configuronic/tree/main/tests/support_package/"
    click TestWF "https://github.com/positronic-robotics/configuronic/blob/main/.github/workflows/test.yml"
    click ReleaseWF "https://github.com/positronic-robotics/configuronic/blob/main/.github/workflows/release.yml"
    click Build "https://github.com/positronic-robotics/configuronic/blob/main/pyproject.toml"
    click Meta "https://github.com/positronic-robotics/configuronic/blob/main/README.md"
    click License "https://github.com/positronic-robotics/configuronic/blob/main/LICENSE.md"

    classDef user fill:#ffe4b5,stroke:#ff8c00
    classDef cli fill:#add8e6,stroke:#1e90ff
    classDef core fill:#98fb98,stroke:#228b22
    classDef runtime fill:#fffacd,stroke:#ffd700
    classDef infra fill:#d3d3d3,stroke:#696969
```
