# cjh-blip/optiflow architecture

> Architecture diagram of the GitHub repository cjh-blip/optiflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cjh-blip/optiflow
- Repository: https://github.com/cjh-blip/optiflow

## Overview

OptiFlow turns a lighting goal into a predicted layout and a DIALux-importable STF file. The documented main journey starts at the browser shell or an agent-facing protocol, passes through a shared service and orchestrator, and dispatches distinct algorithm and file-adapter steps. The plan artifact is the handoff between those steps; results include checks and stated model limits. The README also describes DXF import and IR validation. Their exact runtime wiring, and the unsampled HTTP/MCP handlers, are not inferred beyond documented boundaries.

Main entry points: [`src/optiflow/service.py`](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/service.py) (Platform service), [`src/optiflow/orchestrator.py`](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/orchestrator.py) (Pipeline orchestrator), [`src/optiflow/algo/engine.py`](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/engine.py) (Planning engine), [`src/optiflow/adapters/dialux/adapter.py`](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/adapter.py) (DIALux adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_shell["Browser shell<br/>[shell.py]"]
  node_http["HTTP API<br/>[api.py]"]
  node_mcp["MCP server<br/>[mcp.py]"]
end

subgraph group_coordination["Service and orchestration"]
  node_service["Platform service<br/>[service.py]"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
  node_registry["Adapter registry<br/>[registry.py]"]
  node_pipeline["Lighting pipeline<br/>[pipelines.py]"]
  node_dispatcher["Step dispatcher<br/>[dispatcher.py]"]
end

subgraph group_planning["Lighting planning"]
  node_lumen_adapter["Lumen adapter<br/>[lumen.py]"]
  node_engine["Planning engine<br/>[engine.py]"]
  node_layout["Fixture layout<br/>[layout.py]"]
  node_uniformity["Uniformity analysis<br/>[uniformity.py]"]
  node_geometry["Shared geometry<br/>[geometry.py]"]
end

subgraph group_dialux["DIALux file adapter"]
  node_dialux_adapter["DIALux adapter<br/>[adapter.py]"]
  node_dxf["DXF import<br/>[dxf.py]"]
  node_stf["STF export<br/>[stf.py]"]
  node_xlsx["XLSX parsing<br/>[xlsx.py]"]
end

subgraph group_models["Shared models"]
  node_plan_file["Plan artifact"]
  node_ir["Task and shared IR<br/>[ir.py]"]
  node_job["Job and results<br/>[job.py]"]
  node_project["Project versions<br/>[project.py]"]
  node_validator["IR validator<br/>[__init__.py]"]
end

node_user(("User or agent"))
node_dialux_software(("DIALux"))

node_user -->|"enters goal"| node_shell
node_user -->|"calls"| node_http
node_user -->|"calls"| node_mcp
node_shell -->|"fetches"| node_http
node_http -->|"translates requests"| node_service
node_mcp -->|"translates requests"| node_service
node_service -->|"runs jobs"| node_orchestrator
node_service -->|"lists capabilities"| node_registry
node_service -->|"selects pipeline"| node_pipeline
node_orchestrator -->|"runs steps"| node_pipeline
node_orchestrator -->|"resolves adapters"| node_registry
node_orchestrator -->|"dispatches steps"| node_dispatcher
node_dispatcher -->|"submits step"| node_lumen_adapter
node_dispatcher -->|"submits step"| node_dialux_adapter
node_lumen_adapter -->|"plans layout"| node_engine
node_engine -->|"arranges fixtures"| node_layout
node_engine -->|"evaluates uniformity"| node_uniformity
node_engine -->|"uses geometry"| node_geometry
node_lumen_adapter -->|"writes plan"| node_plan_file
node_pipeline -->|"reads plan"| node_plan_file
node_pipeline -->|"rebuilds task"| node_ir
node_dialux_adapter -->|"exports through"| node_stf
node_dialux_adapter -->|"imports through"| node_dxf
node_dialux_adapter -.->|"parses optionally"| node_xlsx
node_dxf -->|"produces geometry"| node_ir
node_stf -->|"creates import file"| node_dialux_software
node_service -->|"tracks jobs"| node_job
node_orchestrator -->|"archives steps"| node_project
node_validator -->|"validates"| node_ir

click node_shell "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/shell.py"
click node_http "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/api.py"
click node_mcp "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/mcp.py"
click node_service "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/service.py"
click node_orchestrator "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/orchestrator.py"
click node_registry "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/registry.py"
click node_pipeline "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/pipelines.py"
click node_dispatcher "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/dispatcher.py"
click node_lumen_adapter "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/lumen.py"
click node_engine "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/engine.py"
click node_layout "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/layout.py"
click node_uniformity "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/uniformity.py"
click node_geometry "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/geometry.py"
click node_dialux_adapter "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/adapter.py"
click node_dxf "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/dxf.py"
click node_stf "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/stf.py"
click node_xlsx "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/xlsx.py"
click node_ir "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/ir.py"
click node_job "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/job.py"
click node_project "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/project.py"
click node_validator "https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/validator/__init__.py"

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_shell,node_http,node_mcp,node_user toneBlue
class node_service,node_orchestrator,node_registry,node_pipeline,node_dispatcher toneAmber
class node_lumen_adapter,node_engine,node_layout,node_uniformity,node_geometry toneMint
class node_dialux_adapter,node_dxf,node_stf,node_xlsx toneRose
class node_plan_file,node_ir,node_job,node_project,node_validator,node_dialux_software toneIndigo
```

## Components

### User interfaces

- [Browser shell](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/shell.py): `src/optiflow/shell.py`
- [HTTP API](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/api.py): `src/optiflow/api.py`
- [MCP server](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/mcp.py): `src/optiflow/mcp.py`

### Service and orchestration

- [Platform service](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/service.py): `src/optiflow/service.py`
- [Pipeline orchestrator](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/orchestrator.py): `src/optiflow/orchestrator.py`
- [Adapter registry](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/registry.py): `src/optiflow/registry.py`
- [Lighting pipeline](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/pipelines.py): `src/optiflow/pipelines.py`
- [Step dispatcher](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/dispatcher.py): `src/optiflow/dispatcher.py`

### Lighting planning

- [Lumen adapter](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/lumen.py): `src/optiflow/adapters/lumen.py`
- [Planning engine](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/engine.py): `src/optiflow/algo/engine.py`
- [Fixture layout](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/layout.py): `src/optiflow/algo/layout.py`
- [Uniformity analysis](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/algo/uniformity.py): `src/optiflow/algo/uniformity.py`
- [Shared geometry](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/geometry.py): `src/optiflow/geometry.py`

### DIALux file adapter

- [DIALux adapter](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/adapter.py): `src/optiflow/adapters/dialux/adapter.py`
- [DXF import](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/dxf.py): `src/optiflow/adapters/dialux/dxf.py`
- [STF export](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/stf.py): `src/optiflow/adapters/dialux/stf.py`
- [XLSX parsing](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/adapters/dialux/xlsx.py): `src/optiflow/adapters/dialux/xlsx.py`

### Shared models

- **Plan artifact**
- [Task and shared IR](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/ir.py): `src/optiflow/ir.py`
- [Job and results](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/job.py): `src/optiflow/job.py`
- [Project versions](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/project.py): `src/optiflow/project.py`
- [IR validator](https://github.com/cjh-blip/optiflow/blob/main/src/optiflow/validator/__init__.py): `src/optiflow/validator/__init__.py`

### Other components

- **User or agent**
- **DIALux**

## Connections

- User or agent → Browser shell: enters goal
- User or agent → HTTP API: calls
- User or agent → MCP server: calls
- Browser shell → HTTP API: fetches
- HTTP API → Platform service: translates requests
- MCP server → Platform service: translates requests
- Platform service → Pipeline orchestrator: runs jobs
- Platform service → Adapter registry: lists capabilities
- Platform service → Lighting pipeline: selects pipeline
- Pipeline orchestrator → Lighting pipeline: runs steps
- Pipeline orchestrator → Adapter registry: resolves adapters
- Pipeline orchestrator → Step dispatcher: dispatches steps
- Step dispatcher → Lumen adapter: submits step
- Step dispatcher → DIALux adapter: submits step
- Lumen adapter → Planning engine: plans layout
- Planning engine → Fixture layout: arranges fixtures
- Planning engine → Uniformity analysis: evaluates uniformity
- Planning engine → Shared geometry: uses geometry
- Lumen adapter → Plan artifact: writes plan
- Lighting pipeline → Plan artifact: reads plan
- Lighting pipeline → Task and shared IR: rebuilds task
- DIALux adapter → STF export: exports through
- DIALux adapter → DXF import: imports through
- DIALux adapter → XLSX parsing: parses optionally
- DXF import → Task and shared IR: produces geometry
- STF export → DIALux: creates import file
- Platform service → Job and results: tracks jobs
- Pipeline orchestrator → Project versions: archives steps
- IR validator → Task and shared IR: validates