# andyferns/oqci architecture

> Architecture diagram of the GitHub repository andyferns/oqci, 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/andyferns/oqci
- Repository: https://github.com/andyferns/oqci

## Overview

OQCI is a vendor-neutral quantum-circuit compiler: source circuits are translated into shared IR, optimized, lowered for a selected target, then prepared as backend executables. The graph also shows the local visualization companion and simulator adapters, which are documented product capabilities. Compiler orchestration and lowering details are only partly sampled, so their internal wiring is shown at the documented subsystem level; IBM submission is explicitly not implemented.

Main entry points: [`src/compile.rs`](https://github.com/andyferns/oqci/blob/master/src/compile.rs) (Compiler orchestration), [`src/ir/qc.rs`](https://github.com/andyferns/oqci/blob/master/src/ir/qc.rs) (QC-IR), [`src/backend/mod.rs`](https://github.com/andyferns/oqci/blob/master/src/backend/mod.rs) (Backend contract), [`src/lowering/mod.rs`](https://github.com/andyferns/oqci/blob/master/src/lowering/mod.rs) (Target lowering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Inputs and visualization"]
  node_cli["CLI pipeline<br/>[pipeline.rs]"]
  node_python["Python bindings<br/>[lib.rs]"]
end

subgraph group_compiler["Compiler pipeline"]
  node_qasm["OpenQASM frontend<br/>[mod.rs]"]
  node_cudaq["CUDA-Q frontend<br/>[mod.rs]"]
  node_qiskit["Qiskit frontend<br/>[mod.rs]"]
  node_compile["Compiler orchestration<br/>[compile.rs]"]
  node_qc_ir["QC-IR<br/>[qc.rs]"]
  node_qco_ir["QCO-IR<br/>[qco.rs]"]
  node_passes["Pass manager<br/>[mod.rs]"]
  node_qir["QIR lowering<br/>[qir.rs]"]
end

subgraph group_targets["Targets and execution"]
  node_target["Target profile<br/>[mod.rs]"]
  node_lowering["Target lowering<br/>[mod.rs]"]
  node_legality["Legality checks<br/>[legality.rs]"]
  node_backend["Backend contract<br/>[mod.rs]"]
  node_executable["Executable artifact<br/>[executable.rs]"]
  node_simulator["Simulator backend<br/>[simulator.rs]"]
  node_aer["Qiskit Aer adapter<br/>[aer.py]"]
  node_cudaq_adapter["CUDA-Q adapter<br/>[cudaq.py]"]
end

subgraph group_visualization["Live visualization"]
  node_ui["Pipeline visualizer<br/>[App.tsx]"]
  node_store["Pipeline state<br/>[pipelineStore.ts]"]
  node_ws["WebSocket client<br/>[client.ts]"]
  node_server["Visualization server<br/>[main.rs]"]
  node_watch["File watch<br/>[watch.rs]"]
  node_server_compile["Server compilation<br/>[compile.rs]"]
end

node_source(("Circuit source"))
node_browser(("Browser user"))

node_source -->|"provides source"| node_cli
node_source -->|"provides circuit"| node_python
node_cli -->|"invokes"| node_compile
node_python -->|"compiles via"| node_compile
node_compile -->|"selects frontend"| node_qasm
node_compile -->|"selects frontend"| node_cudaq
node_compile -->|"selects frontend"| node_qiskit
node_qasm -->|"translates to"| node_qc_ir
node_cudaq -->|"translates to"| node_qc_ir
node_qiskit -->|"translates to"| node_qc_ir
node_compile -->|"runs passes"| node_passes
node_qc_ir -->|"converts to"| node_qco_ir
node_passes -->|"optimizes"| node_qc_ir
node_compile -->|"emits"| node_qir
node_compile -->|"requests lowering"| node_lowering
node_backend -->|"provides profile"| node_target
node_lowering -->|"uses profile"| node_target
node_lowering -->|"checks output"| node_legality
node_backend -->|"lowers circuit"| node_lowering
node_backend -->|"prepares"| node_executable
node_backend -->|"executes"| node_simulator
node_executable -.->|"runs artifact"| node_aer
node_executable -.->|"runs artifact"| node_cudaq_adapter
node_browser -->|"views pipeline"| node_ui
node_ui -->|"connects to"| node_ws
node_ws -->|"opens socket"| node_server
node_server -->|"starts watch"| node_watch
node_watch -->|"signals changes"| node_server_compile
node_server_compile -->|"calls compiler"| node_compile
node_server_compile -->|"streams reports"| node_ws
node_ws -->|"delivers events"| node_store
node_store -->|"supplies state"| node_ui

click node_cli "https://github.com/andyferns/oqci/blob/master/src/cli/pipeline.rs"
click node_python "https://github.com/andyferns/oqci/blob/master/python/src/lib.rs"
click node_qasm "https://github.com/andyferns/oqci/blob/master/src/frontend/openqasm/mod.rs"
click node_cudaq "https://github.com/andyferns/oqci/blob/master/src/frontend/cudaq/mod.rs"
click node_qiskit "https://github.com/andyferns/oqci/blob/master/src/frontend/qiskit/mod.rs"
click node_compile "https://github.com/andyferns/oqci/blob/master/src/compile.rs"
click node_qc_ir "https://github.com/andyferns/oqci/blob/master/src/ir/qc.rs"
click node_qco_ir "https://github.com/andyferns/oqci/blob/master/src/ir/qco.rs"
click node_passes "https://github.com/andyferns/oqci/blob/master/src/pass/mod.rs"
click node_qir "https://github.com/andyferns/oqci/blob/master/src/ir/qir.rs"
click node_target "https://github.com/andyferns/oqci/blob/master/src/target/mod.rs"
click node_lowering "https://github.com/andyferns/oqci/blob/master/src/lowering/mod.rs"
click node_legality "https://github.com/andyferns/oqci/blob/master/src/target/legality.rs"
click node_backend "https://github.com/andyferns/oqci/blob/master/src/backend/mod.rs"
click node_executable "https://github.com/andyferns/oqci/blob/master/src/backend/executable.rs"
click node_simulator "https://github.com/andyferns/oqci/blob/master/src/backend/simulator.rs"
click node_aer "https://github.com/andyferns/oqci/blob/master/python/oqci/backends/aer.py"
click node_cudaq_adapter "https://github.com/andyferns/oqci/blob/master/python/oqci/backends/cudaq.py"
click node_ui "https://github.com/andyferns/oqci/blob/master/frontend/src/App.tsx"
click node_store "https://github.com/andyferns/oqci/blob/master/frontend/src/state/pipelineStore.ts"
click node_ws "https://github.com/andyferns/oqci/blob/master/frontend/src/ws/client.ts"
click node_server "https://github.com/andyferns/oqci/blob/master/server/src/main.rs"
click node_watch "https://github.com/andyferns/oqci/blob/master/server/src/watch.rs"
click node_server_compile "https://github.com/andyferns/oqci/blob/master/server/src/compile.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_cli,node_python,node_browser toneBlue
class node_qasm,node_cudaq,node_qiskit,node_compile,node_qc_ir,node_qco_ir,node_passes,node_qir toneAmber
class node_target,node_lowering,node_legality,node_backend,node_executable,node_simulator,node_aer,node_cudaq_adapter toneMint
class node_ui,node_store,node_ws,node_server,node_watch,node_server_compile toneRose
class node_source toneIndigo
```

## Components

### Inputs and visualization

- [CLI pipeline](https://github.com/andyferns/oqci/blob/master/src/cli/pipeline.rs): `src/cli/pipeline.rs`
- [Python bindings](https://github.com/andyferns/oqci/blob/master/python/src/lib.rs): `python/src/lib.rs`

### Compiler pipeline

- [OpenQASM frontend](https://github.com/andyferns/oqci/blob/master/src/frontend/openqasm/mod.rs): `src/frontend/openqasm/mod.rs`
- [CUDA-Q frontend](https://github.com/andyferns/oqci/blob/master/src/frontend/cudaq/mod.rs): `src/frontend/cudaq/mod.rs`
- [Qiskit frontend](https://github.com/andyferns/oqci/blob/master/src/frontend/qiskit/mod.rs): `src/frontend/qiskit/mod.rs`
- [Compiler orchestration](https://github.com/andyferns/oqci/blob/master/src/compile.rs): `src/compile.rs`
- [QC-IR](https://github.com/andyferns/oqci/blob/master/src/ir/qc.rs): `src/ir/qc.rs`
- [QCO-IR](https://github.com/andyferns/oqci/blob/master/src/ir/qco.rs): `src/ir/qco.rs`
- [Pass manager](https://github.com/andyferns/oqci/blob/master/src/pass/mod.rs): `src/pass/mod.rs`
- [QIR lowering](https://github.com/andyferns/oqci/blob/master/src/ir/qir.rs): `src/ir/qir.rs`

### Targets and execution

- [Target profile](https://github.com/andyferns/oqci/blob/master/src/target/mod.rs): `src/target/mod.rs`
- [Target lowering](https://github.com/andyferns/oqci/blob/master/src/lowering/mod.rs): `src/lowering/mod.rs`
- [Legality checks](https://github.com/andyferns/oqci/blob/master/src/target/legality.rs): `src/target/legality.rs`
- [Backend contract](https://github.com/andyferns/oqci/blob/master/src/backend/mod.rs): `src/backend/mod.rs`
- [Executable artifact](https://github.com/andyferns/oqci/blob/master/src/backend/executable.rs): `src/backend/executable.rs`
- [Simulator backend](https://github.com/andyferns/oqci/blob/master/src/backend/simulator.rs): `src/backend/simulator.rs`
- [Qiskit Aer adapter](https://github.com/andyferns/oqci/blob/master/python/oqci/backends/aer.py): `python/oqci/backends/aer.py`
- [CUDA-Q adapter](https://github.com/andyferns/oqci/blob/master/python/oqci/backends/cudaq.py): `python/oqci/backends/cudaq.py`

### Live visualization

- [Pipeline visualizer](https://github.com/andyferns/oqci/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Pipeline state](https://github.com/andyferns/oqci/blob/master/frontend/src/state/pipelineStore.ts): `frontend/src/state/pipelineStore.ts`
- [WebSocket client](https://github.com/andyferns/oqci/blob/master/frontend/src/ws/client.ts): `frontend/src/ws/client.ts`
- [Visualization server](https://github.com/andyferns/oqci/blob/master/server/src/main.rs): `server/src/main.rs`
- [File watch](https://github.com/andyferns/oqci/blob/master/server/src/watch.rs): `server/src/watch.rs`
- [Server compilation](https://github.com/andyferns/oqci/blob/master/server/src/compile.rs): `server/src/compile.rs`

### Other components

- **Circuit source**
- **Browser user**

## Connections

- Circuit source → CLI pipeline: provides source
- Circuit source → Python bindings: provides circuit
- CLI pipeline → Compiler orchestration: invokes
- Python bindings → Compiler orchestration: compiles via
- Compiler orchestration → OpenQASM frontend: selects frontend
- Compiler orchestration → CUDA-Q frontend: selects frontend
- Compiler orchestration → Qiskit frontend: selects frontend
- OpenQASM frontend → QC-IR: translates to
- CUDA-Q frontend → QC-IR: translates to
- Qiskit frontend → QC-IR: translates to
- Compiler orchestration → Pass manager: runs passes
- QC-IR → QCO-IR: converts to
- Pass manager → QC-IR: optimizes
- Compiler orchestration → QIR lowering: emits
- Compiler orchestration → Target lowering: requests lowering
- Backend contract → Target profile: provides profile
- Target lowering → Target profile: uses profile
- Target lowering → Legality checks: checks output
- Backend contract → Target lowering: lowers circuit
- Backend contract → Executable artifact: prepares
- Backend contract → Simulator backend: executes
- Executable artifact → Qiskit Aer adapter: runs artifact
- Executable artifact → CUDA-Q adapter: runs artifact
- Browser user → Pipeline visualizer: views pipeline
- Pipeline visualizer → WebSocket client: connects to
- WebSocket client → Visualization server: opens socket
- Visualization server → File watch: starts watch
- File watch → Server compilation: signals changes
- Server compilation → Compiler orchestration: calls compiler
- Server compilation → WebSocket client: streams reports
- WebSocket client → Pipeline state: delivers events
- Pipeline state → Pipeline visualizer: supplies state