# darkshapes/zodiac architecture

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

- Interactive diagram: https://gitdiagram.com/darkshapes/zodiac
- Repository: https://github.com/darkshapes/zodiac

## Overview

##### Project type and purpose
- Zodiac is a local-first, privacy-oriented Python application that runs on CLI, TUI, smartphone and browser environments. Its goal is to let artists and researchers visually compose and execute generative-AI “action chains” without writing code.

##### High-level architecture from the file tree and README
- Two main Python packages:
- astra/ – a lightweight theming & widget CSS (TUI/CSS) library (.tcss) plus entrypoint.
- zodiac/ – the core app: UI screens (main_screen.py), widget modules (carousel.py, flip.py, display_bar.py, etc.), a graph-based workflow engine (graph.py, combo.tcss), and a model-registry for plugging in local LLM runtimes.
- No external server or datastore; everything runs locally and interacts with local model runtimes (Ollama, VLLM, LMStudio, etc.) via plugin connectors.

##### Main components
A. UI Layer (frontend)
- CLI / Terminal UI with astra theming (astra/__main__.py + .tcss)
- Smartphone UI (same codebase, adaptive TUI/CSS)
- Browser UI (served locally by the app if used in web mode)
B. Core Engine (backend)
1. Workflow Manager – constructs and sequences action chains
2. Graph Manager – maintains the directed graph data structure (zodiac/graph.py)
3. Model Registry – discovers and registers local model providers (zodiac/token_counters.py, model_register tests)
4. Widget Manager – mounts and lays out widgets (carousel, flip, panels) via astra
C. Plugin Connectors (local services)
- Ollama, Llamafile, VLLM, LMStudio, etc. – each accessed through a small adapter layer in zodiac/
D. Local File System
- Configuration files (pyproject.toml, .python-version)
- Optional workflow persistence (if extended)
E. Tests & CI
- pytest suite (tests/)
- GitHub Actions (python-app.yml)

##### Relationships and data flows
1. User → UI Layer: enters text/audio/files.
2. UI → Core Engine: user commands invoke the Workflow Manager.
3. Workflow Manager ↔ Graph Manager: build or modify the node/edge graph.
4. Core Engine → Model Registry: find the right local model adapter.
5. Core Engine → Plugin Connector → Local Model Runtime: send prompts, receive results.
6. Core Engine → Widget Manager → UI: render outputs to screen.
7. Optionally Core Engine → File System: read/write workflow definitions or caches.

##### Architectural patterns & design principles
- MVC-style separation: UI layer (View) is decoupled from business logic (Controller = Core Engine) and data (Model = Graph Manager + Model Registry).
- Plugin-based extensibility: new local model runtimes or UI widgets can be dropped in without touching core.
- Graph data structure for workflow orchestration (adds/removes nodes & edges at runtime).
- Theming layer (astra) isolates CSS/TUI styling from widget implementations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        CLI["CLI / Terminal UI"]:::ui
        TUIStyles["astra/button.tcss"]:::ui
        MainScreen["Main Screen Controller"]:::ui
        Carousel["Carousel Widget"]:::ui
        Flip["Flip Widget"]:::ui
        DisplayBar["Display / Status Bar"]:::ui
        MessagePanel["Message Panel"]:::ui
        ResponsePanel["Response Panel"]:::ui
        VoicePanel["Voice Input Panel"]:::ui
        InputTag["Input Tag Widget"]:::ui
        OutputTag["Output Tag Widget"]:::ui
        Picker["Picker Widget"]:::ui
        ComboCSS["Shared Styling (combo.tcss)"]:::ui
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        WorkflowMgr["Workflow Manager"]:::core
        GraphMgr["Graph Manager"]:::core
        ModelReg["Model Registry"]:::core
        WidgetMgr["Widget Manager"]:::core
    end

    %% Plugin Connectors
    subgraph "Plugin Connectors" 
        direction TB
        Adapter["Plugin Adapter Layer"]:::plugin
        Ollama(("Ollama")):::plugin
        VLLM(("VLLM")):::plugin
        LMStudio(("LMStudio")):::plugin
    end

    %% File System
    subgraph "Local File System" 
        direction TB
        Config(("pyproject.toml")):::fs
        Version((".python-version")):::fs
    end

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        Pytest["tests/"]:::fs
        CI[".github/workflows/python-app.yml"]:::fs
    end

    %% Relationships
    User["User"] -->|"enters input"| CLI
    User -->|"enters input"| MainScreen

    CLI -->|"invoke commands"| WorkflowMgr
    MainScreen -->|"invoke commands"| WorkflowMgr

    WorkflowMgr -->|"build/modify graph"| GraphMgr
    GraphMgr -->|"state updates"| WorkflowMgr

    WorkflowMgr -->|"query registry"| ModelReg
    ModelReg -->|"adapter selection"| WorkflowMgr

    WorkflowMgr -->|"invoke widget render"| WidgetMgr
    WidgetMgr -->|"render output"| MainScreen

    WorkflowMgr -->|"invoke model"| Adapter
    Adapter -->|"send prompts"| Ollama
    Adapter -->|"send prompts"| VLLM
    Adapter -->|"send prompts"| LMStudio
    Ollama -->|"return result"| Adapter
    VLLM -->|"return result"| Adapter
    LMStudio -->|"return result"| Adapter
    Adapter -->|"return model output"| WorkflowMgr

    WorkflowMgr -->|"read/write workflows"| Config
    WorkflowMgr -->|"read/write workflows"| Version

    CI -->|"runs tests"| Pytest

    %% Click events
    click CLI "https://github.com/darkshapes/zodiac/blob/main/astra/__main__.py"
    click TUIStyles "https://github.com/darkshapes/zodiac/blob/main/astra/button.tcss"
    click MainScreen "https://github.com/darkshapes/zodiac/blob/main/zodiac/main_screen.py"
    click Carousel "https://github.com/darkshapes/zodiac/blob/main/zodiac/carousel.py"
    click Flip "https://github.com/darkshapes/zodiac/blob/main/zodiac/flip.py"
    click DisplayBar "https://github.com/darkshapes/zodiac/blob/main/zodiac/display_bar.py"
    click MessagePanel "https://github.com/darkshapes/zodiac/blob/main/zodiac/message_panel.py"
    click ResponsePanel "https://github.com/darkshapes/zodiac/blob/main/zodiac/response_panel.py"
    click VoicePanel "https://github.com/darkshapes/zodiac/blob/main/zodiac/voice_panel.py"
    click InputTag "https://github.com/darkshapes/zodiac/blob/main/zodiac/input_tag.py"
    click OutputTag "https://github.com/darkshapes/zodiac/blob/main/zodiac/output_tag.py"
    click Picker "https://github.com/darkshapes/zodiac/blob/main/zodiac/selectah.py"
    click ComboCSS "https://github.com/darkshapes/zodiac/blob/main/zodiac/combo.tcss"
    click GraphMgr "https://github.com/darkshapes/zodiac/blob/main/zodiac/graph.py"
    click ModelReg "https://github.com/darkshapes/zodiac/blob/main/zodiac/token_counters.py"
    click ZodiacEntrypoint "https://github.com/darkshapes/zodiac/blob/main/zodiac/__main__.py"
    click Config "https://github.com/darkshapes/zodiac/blob/main/pyproject.toml"
    click Version "https://github.com/darkshapes/zodiac/blob/main/.python-version"
    click Pytest "https://github.com/darkshapes/zodiac/tree/main/tests/"
    click CI "https://github.com/darkshapes/zodiac/blob/main/.github/workflows/python-app.yml"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#004085,color:#004085,stroke-width:1px
    classDef core fill:#D4EDDA,stroke:#155724,color:#155724,stroke-width:1px
    classDef plugin fill:#FFF3CD,stroke:#856404,color:#856404,stroke-width:1px
    classDef fs fill:#E2E3E5,stroke:#6C757D,color:#6C757D,stroke-width:1px
```
