# 0xgh0stan0n/syrup architecture

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

- Interactive diagram: https://gitdiagram.com/0xgh0stan0n/syrup
- Repository: https://github.com/0xgh0stan0n/syrup

## Overview

Syrup turns operation names into typed visual-detection programs, then executes them on image frames and returns structured, confidence-scored observations. The main path is name resolution, planning, code generation, compilation and validation, followed by loading and execution through detector providers. Python, Rust and the CLI expose this workflow; the core library also offers direct image primitives and live window capture. Runtime wiring is supported by the SOURCE INDEX; several capabilities are documented in the README but their implementation details were not sampled.

Main entry points: [`crates/syrup-runtime/src/runtime.rs`](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/runtime.rs) (Runtime orchestration), [`src/capture/mod.rs`](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/mod.rs) (Window capture API), [`crates/syrup-runtime/src/plan.rs`](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/plan.rs) (Typed planner), [`python/syrup/__init__.py`](https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/__init__.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_python_ops["Named operations<br/>[ops.py]"]
  node_planner["Optional planner<br/>[planner.py]"]
  node_recipes["Model recipes<br/>[recipes.py]"]
  node_native["Python binding<br/>[lib.rs]"]
  node_cli["CLI<br/>[syrup.rs]"]
end

subgraph group_runtime["Operation runtime"]
  node_runtime_api["Runtime orchestration<br/>[runtime.rs]"]
  node_intent["Intent parser<br/>[intent.rs]"]
  node_catalog["Target catalog<br/>[catalog.rs]"]
  node_plan["Typed planner<br/>[plan.rs]"]
  node_codegen["Rust codegen<br/>[codegen.rs]"]
  node_compiler["Module compiler<br/>[compiler.rs]"]
  node_validator["Plan validator<br/>[validate.rs]"]
  node_cache[("Artifact cache<br/>[cache.rs]")]
  node_loader["Module loader<br/>[loader.rs]"]
  node_executor["Module execution<br/>[interp.rs]"]
  node_providers["Detection providers<br/>[mod.rs]"]
  node_custom["Custom detectors<br/>[custom.rs]"]
end

subgraph group_vision["Vision primitives"]
  node_core["Image primitives<br/>[geometry.rs]"]
  node_color["Color predicates<br/>[color.rs]"]
  node_motion["Motion detection<br/>[motion.rs]"]
  node_tracking["Region tracking<br/>[tracking.rs]"]
  node_ocr["OCR<br/>[mod.rs]"]
  node_quality["Sharpness quality<br/>[quality.rs]"]
  node_detection["Result contract<br/>[detection.rs]"]
  node_drawing["Debug drawing<br/>[draw.rs]"]
end

subgraph group_capture["Window capture"]
  node_capture_api["Window capture API<br/>[mod.rs]"]
  node_capture_portal["Wayland portal<br/>[portal.rs]"]
  node_pipewire["PipeWire frames<br/>[pipewire.rs]"]
  node_x11["X11 capture<br/>[x11.rs]"]
  node_platform["Platform capture<br/>[windows.rs]"]
end

node_user(("Application user"))
node_rustc["rustc"]

node_user -->|"names operation"| node_python_ops
node_python_ops -->|"resolves calls"| node_python_api
node_python_api -->|"calls binding"| node_native
node_native -.->|"invokes runtime"| node_runtime_api
node_user -->|"requests definition"| node_planner
node_planner -->|"defines operation"| node_python_api
node_user -->|"registers models"| node_recipes
node_recipes -->|"registers targets"| node_python_api
node_user -->|"runs command"| node_cli
node_cli -.->|"invokes runtime"| node_runtime_api
node_runtime_api -->|"resolves name"| node_intent
node_intent -->|"looks up targets"| node_catalog
node_runtime_api -->|"builds plan"| node_plan
node_plan -->|"uses intent"| node_intent
node_plan -->|"reads finder rules"| node_catalog
node_runtime_api -->|"generates module"| node_codegen
node_codegen -->|"renders steps"| node_plan
node_runtime_api -->|"compiles module"| node_compiler
node_compiler -->|"invokes compiler"| node_rustc
node_runtime_api -->|"validates output"| node_validator
node_validator -->|"checks reference"| node_executor
node_runtime_api -->|"reuses artifacts"| node_cache
node_cache -->|"builds missing artifact"| node_compiler
node_runtime_api -->|"loads module"| node_loader
node_runtime_api -->|"executes operation"| node_executor
node_runtime_api -->|"dispatches detection"| node_providers
node_providers -->|"looks up custom"| node_custom
node_user -->|"requests window frames"| node_capture_api
node_capture_api -->|"uses Wayland portal"| node_capture_portal
node_capture_portal -->|"receives frames"| node_pipewire
node_capture_api -->|"dispatches X11"| node_x11
node_capture_api -->|"dispatches Windows"| node_platform
node_user -->|"analyzes frames"| node_core
node_core -->|"uses predicates"| node_color
node_user -->|"measures movement"| node_motion
node_motion -->|"tracks regions"| node_tracking
node_user -->|"recognizes text"| node_ocr
node_user -->|"checks readability"| node_quality
node_user -->|"annotates results"| node_drawing
node_core -.->|"returns observations"| node_detection
node_motion -->|"returns observations"| node_detection
node_tracking -->|"returns tracked results"| node_detection

click node_python_api "https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/__init__.py"
click node_python_ops "https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/ops.py"
click node_planner "https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/planner.py"
click node_recipes "https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/recipes.py"
click node_native "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-python/src/lib.rs"
click node_cli "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/bin/syrup.rs"
click node_runtime_api "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/runtime.rs"
click node_intent "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/intent.rs"
click node_catalog "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/catalog.rs"
click node_plan "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/plan.rs"
click node_codegen "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/codegen.rs"
click node_compiler "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/compiler.rs"
click node_validator "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/validate.rs"
click node_cache "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/cache.rs"
click node_loader "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/loader.rs"
click node_executor "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/interp.rs"
click node_providers "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/providers/mod.rs"
click node_custom "https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/custom.rs"
click node_core "https://github.com/0xgh0stan0n/syrup/blob/main/src/geometry.rs"
click node_color "https://github.com/0xgh0stan0n/syrup/blob/main/src/color.rs"
click node_motion "https://github.com/0xgh0stan0n/syrup/blob/main/src/motion.rs"
click node_tracking "https://github.com/0xgh0stan0n/syrup/blob/main/src/tracking.rs"
click node_ocr "https://github.com/0xgh0stan0n/syrup/blob/main/src/ocr/mod.rs"
click node_quality "https://github.com/0xgh0stan0n/syrup/blob/main/src/quality.rs"
click node_detection "https://github.com/0xgh0stan0n/syrup/blob/main/src/detection.rs"
click node_drawing "https://github.com/0xgh0stan0n/syrup/blob/main/src/draw.rs"
click node_capture_api "https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/mod.rs"
click node_capture_portal "https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/portal.rs"
click node_pipewire "https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/pipewire.rs"
click node_x11 "https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/x11.rs"
click node_platform "https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/windows.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_api,node_python_ops,node_planner,node_recipes,node_native,node_cli,node_user toneBlue
class node_runtime_api,node_intent,node_catalog,node_plan,node_codegen,node_compiler,node_validator,node_cache,node_loader,node_executor,node_providers,node_custom toneAmber
class node_core,node_color,node_motion,node_tracking,node_ocr,node_quality,node_detection,node_drawing toneMint
class node_capture_api,node_capture_portal,node_pipewire,node_x11,node_platform toneRose
class node_rustc toneIndigo
```

## Components

### User interfaces

- [Python API](https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/__init__.py): `python/syrup/__init__.py`
- [Named operations](https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/ops.py): `python/syrup/ops.py`
- [Optional planner](https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/planner.py): `python/syrup/planner.py`
- [Model recipes](https://github.com/0xgh0stan0n/syrup/blob/main/python/syrup/recipes.py): `python/syrup/recipes.py`
- [Python binding](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-python/src/lib.rs): `crates/syrup-python/src/lib.rs`
- [CLI](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/bin/syrup.rs): `crates/syrup-runtime/src/bin/syrup.rs`

### Operation runtime

- [Runtime orchestration](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/runtime.rs): `crates/syrup-runtime/src/runtime.rs`
- [Intent parser](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/intent.rs): `crates/syrup-runtime/src/intent.rs`
- [Target catalog](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/catalog.rs): `crates/syrup-runtime/src/catalog.rs`
- [Typed planner](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/plan.rs): `crates/syrup-runtime/src/plan.rs`
- [Rust codegen](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/codegen.rs): `crates/syrup-runtime/src/codegen.rs`
- [Module compiler](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/compiler.rs): `crates/syrup-runtime/src/compiler.rs`
- [Plan validator](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/validate.rs): `crates/syrup-runtime/src/validate.rs`
- [Artifact cache](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/cache.rs): `crates/syrup-runtime/src/cache.rs`
- [Module loader](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/loader.rs): `crates/syrup-runtime/src/loader.rs`
- [Module execution](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/interp.rs): `crates/syrup-runtime/src/interp.rs`
- [Detection providers](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/providers/mod.rs): `crates/syrup-runtime/src/providers/mod.rs`
- [Custom detectors](https://github.com/0xgh0stan0n/syrup/blob/main/crates/syrup-runtime/src/custom.rs): `crates/syrup-runtime/src/custom.rs`

### Vision primitives

- [Image primitives](https://github.com/0xgh0stan0n/syrup/blob/main/src/geometry.rs): `src/geometry.rs`
- [Color predicates](https://github.com/0xgh0stan0n/syrup/blob/main/src/color.rs): `src/color.rs`
- [Motion detection](https://github.com/0xgh0stan0n/syrup/blob/main/src/motion.rs): `src/motion.rs`
- [Region tracking](https://github.com/0xgh0stan0n/syrup/blob/main/src/tracking.rs): `src/tracking.rs`
- [OCR](https://github.com/0xgh0stan0n/syrup/blob/main/src/ocr/mod.rs): `src/ocr/mod.rs`
- [Sharpness quality](https://github.com/0xgh0stan0n/syrup/blob/main/src/quality.rs): `src/quality.rs`
- [Result contract](https://github.com/0xgh0stan0n/syrup/blob/main/src/detection.rs): `src/detection.rs`
- [Debug drawing](https://github.com/0xgh0stan0n/syrup/blob/main/src/draw.rs): `src/draw.rs`

### Window capture

- [Window capture API](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/mod.rs): `src/capture/mod.rs`
- [Wayland portal](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/portal.rs): `src/capture/portal.rs`
- [PipeWire frames](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/pipewire.rs): `src/capture/pipewire.rs`
- [X11 capture](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/x11.rs): `src/capture/x11.rs`
- [Platform capture](https://github.com/0xgh0stan0n/syrup/blob/main/src/capture/windows.rs): `src/capture/windows.rs`

### Other components

- **Application user**
- **rustc**

## Connections

- Application user → Named operations: names operation (evidence: `README.md`)
- Named operations → Python API: resolves calls (evidence: `python/syrup/ops.py`)
- Python API → Python binding: calls binding (evidence: `python/syrup/__init__.py`)
- Python binding → Runtime orchestration: invokes runtime (evidence: `README.md`)
- Application user → Optional planner: requests definition (evidence: `README.md`)
- Optional planner → Python API: defines operation (evidence: `python/syrup/planner.py`)
- Application user → Model recipes: registers models (evidence: `README.md`)
- Model recipes → Python API: registers targets (evidence: `python/syrup/recipes.py`)
- Application user → CLI: runs command (evidence: `README.md`)
- CLI → Runtime orchestration: invokes runtime (evidence: `README.md`)
- Runtime orchestration → Intent parser: resolves name (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Intent parser → Target catalog: looks up targets (evidence: `crates/syrup-runtime/src/intent.rs`)
- Runtime orchestration → Typed planner: builds plan (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Typed planner → Intent parser: uses intent (evidence: `crates/syrup-runtime/src/plan.rs`)
- Typed planner → Target catalog: reads finder rules (evidence: `crates/syrup-runtime/src/plan.rs`)
- Runtime orchestration → Rust codegen: generates module (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Rust codegen → Typed planner: renders steps (evidence: `crates/syrup-runtime/src/codegen.rs`)
- Runtime orchestration → Module compiler: compiles module (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Module compiler → rustc: invokes compiler (evidence: `README.md`)
- Runtime orchestration → Plan validator: validates output (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Plan validator → Module execution: checks reference (evidence: `crates/syrup-runtime/src/validate.rs`)
- Runtime orchestration → Artifact cache: reuses artifacts (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Artifact cache → Module compiler: builds missing artifact (evidence: `crates/syrup-runtime/src/cache.rs`)
- Runtime orchestration → Module loader: loads module (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Runtime orchestration → Module execution: executes operation (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Runtime orchestration → Detection providers: dispatches detection (evidence: `crates/syrup-runtime/src/runtime.rs`)
- Detection providers → Custom detectors: looks up custom (evidence: `crates/syrup-runtime/src/providers/mod.rs`)
- Application user → Window capture API: requests window frames (evidence: `README.md`)
- Window capture API → Wayland portal: uses Wayland portal (evidence: `src/capture/mod.rs`)
- Wayland portal → PipeWire frames: receives frames (evidence: `src/capture/portal.rs`)
- Window capture API → X11 capture: dispatches X11 (evidence: `src/capture/mod.rs`)
- Window capture API → Platform capture: dispatches Windows (evidence: `src/capture/mod.rs`)
- Application user → Image primitives: analyzes frames (evidence: `README.md`)
- Image primitives → Color predicates: uses predicates (evidence: `src/geometry.rs`)
- Application user → Motion detection: measures movement (evidence: `README.md`)
- Motion detection → Region tracking: tracks regions (evidence: `src/motion.rs`)
- Application user → OCR: recognizes text (evidence: `README.md`)
- Application user → Sharpness quality: checks readability (evidence: `README.md`)
- Application user → Debug drawing: annotates results (evidence: `README.md`)
- Image primitives → Result contract: returns observations (evidence: `README.md`)
- Motion detection → Result contract: returns observations (evidence: `src/motion.rs`)
- Region tracking → Result contract: returns tracked results (evidence: `src/tracking.rs`)
