# joshicoding/blind_transpiler architecture

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

- Interactive diagram: https://gitdiagram.com/joshicoding/blind_transpiler
- Repository: https://github.com/joshicoding/blind_transpiler

## Overview

Blind Transpiler converts Qiskit circuits into blind-computation instruction sequences for four protocols, with optional client-supplied keys, then supports materializing those instructions as a circuit. The orchestrator prepares the circuit and dispatches to a protocol controller; each controller maps client operations directly and delegates server-basis gates to its translator. Instructions retain operation roles and metadata. The README documents key estimation/generation and simulation of the resulting circuit. Edges reflect shown imports, calls, or README-described workflow; no simulator or remote service implementation is present in the tree.

Main entry points: [`blind_transpiler/controllers/orchestrator.py`](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/orchestrator.py) (BQC orchestrator), [`blind_transpiler/essentials/bqc_instruction.py`](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/essentials/bqc_instruction.py) (BQC instruction set), [`blind_transpiler/controllers/base.py`](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/base.py) (Controller utilities), [`blind_transpiler/controllers/qhe.py`](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/qhe.py) (QHE controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Circuit API"]
  node_bqc["BQC orchestrator<br/>[orchestrator.py]"]
  node_settings["Protocol settings"]
end

subgraph group_protocols["Protocol controllers"]
  node_controller_base["Controller utilities<br/>[base.py]"]
  node_qhe["QHE controller<br/>[qhe.py]"]
  node_fdqc["FDQC controller<br/>[fdqc.py]"]
  node_ssdqc["SSDQC controller<br/>[ssdqc.py]"]
  node_ubqc["UBQC controller<br/>[ubqc.py]"]
end

subgraph group_translators["Gate translators"]
  node_homomorphic["Homomorphic rules"]
  node_ordered["Ordered-set rules"]
  node_fixed["Fixed-rotation rules"]
  node_recursive["Recursive-rotation rules"]
  node_translator_base["Translation helpers<br/>[base.py]"]
  node_custom_gates["Custom gates<br/>[custom_gates.py]"]
end

subgraph group_instructions["Instruction model"]
  node_bop["Blind operation<br/>[bop.py]"]
  node_instruction["BQC instruction set<br/>[bqc_instruction.py]"]
end

node_user(("Circuit author"))
node_qiskit["Qiskit circuit"]
node_output["Blind circuit"]
node_keys["Encryption keys"]

node_user -->|"creates"| node_qiskit
node_qiskit -->|"provides circuit"| node_bqc
node_bqc -->|"inherits"| node_controller_base
node_bqc -->|"dispatches"| node_qhe
node_bqc -->|"dispatches"| node_fdqc
node_bqc -->|"dispatches"| node_ssdqc
node_bqc -->|"dispatches"| node_ubqc
node_bqc -->|"reads settings"| node_settings
node_controller_base -->|"reads settings"| node_settings
node_qhe -->|"inherits"| node_controller_base
node_fdqc -->|"inherits"| node_controller_base
node_ssdqc -->|"inherits"| node_controller_base
node_ubqc -->|"inherits"| node_controller_base
node_qhe -->|"translates gates"| node_homomorphic
node_fdqc -->|"translates gates"| node_ordered
node_ssdqc -->|"translates gates"| node_fixed
node_ubqc -->|"translates gates"| node_recursive
node_homomorphic -->|"inherits"| node_translator_base
node_ordered -->|"uses helpers"| node_translator_base
node_fixed -->|"inherits"| node_translator_base
node_recursive -->|"inherits"| node_translator_base
node_recursive -->|"reuses rules"| node_homomorphic
node_fixed -->|"uses gates"| node_custom_gates
node_homomorphic -->|"builds operations"| node_bop
node_qhe -->|"builds sequence"| node_instruction
node_fdqc -->|"builds sequence"| node_instruction
node_ssdqc -->|"builds sequence"| node_instruction
node_ubqc -->|"builds sequence"| node_instruction
node_instruction -->|"stores operations"| node_bop
node_instruction -->|"materializes circuit"| node_output
node_user -->|"supplies keys"| node_keys
node_bqc -->|"returns instructions"| node_instruction

click node_bqc "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/orchestrator.py"
click node_settings "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/global_value_store.py"
click node_controller_base "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/base.py"
click node_qhe "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/qhe.py"
click node_fdqc "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/fdqc.py"
click node_ssdqc "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/ssdqc.py"
click node_ubqc "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/ubqc.py"
click node_homomorphic "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/homomorphicTranslator.py"
click node_ordered "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalOrderedSetTranslator.py"
click node_fixed "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalFixedRotationTranslator.py"
click node_recursive "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalRecursiveRotationTranslator.py"
click node_translator_base "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/base.py"
click node_custom_gates "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/custom_gates/custom_gates.py"
click node_bop "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/essentials/bop.py"
click node_instruction "https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/essentials/bqc_instruction.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_bqc,node_settings toneBlue
class node_controller_base,node_qhe,node_fdqc,node_ssdqc,node_ubqc toneAmber
class node_homomorphic,node_ordered,node_fixed,node_recursive,node_translator_base,node_custom_gates toneMint
class node_bop,node_instruction toneRose
class node_user,node_qiskit,node_output,node_keys toneIndigo
```

## Components

### Circuit API

- [BQC orchestrator](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/orchestrator.py): `blind_transpiler/controllers/orchestrator.py`
- [Protocol settings](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/global_value_store.py): `blind_transpiler/global_value_store.py`

### Protocol controllers

- [Controller utilities](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/base.py): `blind_transpiler/controllers/base.py`
- [QHE controller](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/qhe.py): `blind_transpiler/controllers/qhe.py`
- [FDQC controller](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/fdqc.py): `blind_transpiler/controllers/fdqc.py`
- [SSDQC controller](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/ssdqc.py): `blind_transpiler/controllers/ssdqc.py`
- [UBQC controller](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/controllers/ubqc.py): `blind_transpiler/controllers/ubqc.py`

### Gate translators

- [Homomorphic rules](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/homomorphicTranslator.py): `blind_transpiler/translators/homomorphicTranslator.py`
- [Ordered-set rules](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalOrderedSetTranslator.py): `blind_transpiler/translators/universalOrderedSetTranslator.py`
- [Fixed-rotation rules](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalFixedRotationTranslator.py): `blind_transpiler/translators/universalFixedRotationTranslator.py`
- [Recursive-rotation rules](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/universalRecursiveRotationTranslator.py): `blind_transpiler/translators/universalRecursiveRotationTranslator.py`
- [Translation helpers](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/base.py): `blind_transpiler/translators/base.py`
- [Custom gates](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/translators/custom_gates/custom_gates.py): `blind_transpiler/translators/custom_gates/custom_gates.py`

### Instruction model

- [Blind operation](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/essentials/bop.py): `blind_transpiler/essentials/bop.py`
- [BQC instruction set](https://github.com/joshicoding/blind_transpiler/blob/main/blind_transpiler/essentials/bqc_instruction.py): `blind_transpiler/essentials/bqc_instruction.py`

### Other components

- **Circuit author**
- **Qiskit circuit**
- **Blind circuit**
- **Encryption keys**

## Connections

- Circuit author → Qiskit circuit: creates (evidence: `README.md`)
- Qiskit circuit → BQC orchestrator: provides circuit (evidence: `README.md`)
- BQC orchestrator → Controller utilities: inherits (evidence: `blind_transpiler/controllers/orchestrator.py`)
- BQC orchestrator → QHE controller: dispatches (evidence: `blind_transpiler/controllers/orchestrator.py`)
- BQC orchestrator → FDQC controller: dispatches (evidence: `blind_transpiler/controllers/orchestrator.py`)
- BQC orchestrator → SSDQC controller: dispatches (evidence: `blind_transpiler/controllers/orchestrator.py`)
- BQC orchestrator → UBQC controller: dispatches (evidence: `blind_transpiler/controllers/orchestrator.py`)
- BQC orchestrator → Protocol settings: reads settings (evidence: `blind_transpiler/controllers/orchestrator.py`)
- Controller utilities → Protocol settings: reads settings (evidence: `blind_transpiler/controllers/base.py`)
- QHE controller → Controller utilities: inherits (evidence: `blind_transpiler/controllers/qhe.py`)
- FDQC controller → Controller utilities: inherits (evidence: `blind_transpiler/controllers/fdqc.py`)
- SSDQC controller → Controller utilities: inherits (evidence: `blind_transpiler/controllers/ssdqc.py`)
- UBQC controller → Controller utilities: inherits (evidence: `blind_transpiler/controllers/ubqc.py`)
- QHE controller → Homomorphic rules: translates gates (evidence: `blind_transpiler/controllers/qhe.py`)
- FDQC controller → Ordered-set rules: translates gates (evidence: `blind_transpiler/controllers/fdqc.py`)
- SSDQC controller → Fixed-rotation rules: translates gates (evidence: `blind_transpiler/controllers/ssdqc.py`)
- UBQC controller → Recursive-rotation rules: translates gates (evidence: `blind_transpiler/controllers/ubqc.py`)
- Homomorphic rules → Translation helpers: inherits (evidence: `blind_transpiler/translators/homomorphicTranslator.py`)
- Ordered-set rules → Translation helpers: uses helpers (evidence: `blind_transpiler/translators/universalOrderedSetTranslator.py`)
- Fixed-rotation rules → Translation helpers: inherits (evidence: `blind_transpiler/translators/universalFixedRotationTranslator.py`)
- Recursive-rotation rules → Translation helpers: inherits (evidence: `blind_transpiler/translators/universalRecursiveRotationTranslator.py`)
- Recursive-rotation rules → Homomorphic rules: reuses rules (evidence: `blind_transpiler/translators/universalRecursiveRotationTranslator.py`)
- Fixed-rotation rules → Custom gates: uses gates (evidence: `blind_transpiler/translators/universalFixedRotationTranslator.py`)
- Homomorphic rules → Blind operation: builds operations (evidence: `blind_transpiler/translators/homomorphicTranslator.py`)
- QHE controller → BQC instruction set: builds sequence (evidence: `blind_transpiler/controllers/qhe.py`)
- FDQC controller → BQC instruction set: builds sequence (evidence: `blind_transpiler/controllers/fdqc.py`)
- SSDQC controller → BQC instruction set: builds sequence (evidence: `blind_transpiler/controllers/ssdqc.py`)
- UBQC controller → BQC instruction set: builds sequence (evidence: `blind_transpiler/controllers/ubqc.py`)
- BQC instruction set → Blind operation: stores operations (evidence: `blind_transpiler/essentials/bqc_instruction.py`)
- BQC instruction set → Blind circuit: materializes circuit (evidence: `README.md`)
- Circuit author → Encryption keys: supplies keys (evidence: `README.md`)
- BQC orchestrator → BQC instruction set: returns instructions (evidence: `blind_transpiler/controllers/orchestrator.py`)
