# fluxepay/fluxe architecture

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

- Interactive diagram: https://gitdiagram.com/fluxepay/fluxe
- Repository: https://github.com/fluxepay/fluxe

## Overview

Fluxe is a privacy-preserving, compliance-aware stablecoin protocol. Clients construct Groth16 proofs for mint, transfer, burn, or compliance-object updates, then submit proofs and public inputs through the HTTP API. The server verifier checks proofs and deterministically replays state changes, including Merkle roots and supply accounting. Core structures cover confidential notes, compliance objects, callbacks, and Merkle state. The README documents the major circuit capabilities; API routing and verifier internals were not sampled, so those connections reflect documented flows rather than inspected handler implementations.

Main entry points: [`fluxe-circuits/src`](https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-circuits/src) (Transition Circuits), [`fluxe-api/src/client.rs`](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-api/src/client.rs) (API Client), [`fluxe-core/src/state_manager.rs`](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/state_manager.rs) (State Manager), [`fluxe-core/src/server_verifier.rs`](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/server_verifier.rs) (Deterministic Verifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Interface"]
  node_api_client["API Client<br/>[client.rs]"]
  node_http_api["HTTP API<br/>[api.rs]"]
end

subgraph group_proofs["Proof Construction"]
  node_circuit_suite["Transition Circuits"]
  node_circuit_gadgets["ZK Gadgets"]
  node_proof_setup["Proof Setup<br/>[setup.rs]"]
end

subgraph group_protocol["Protocol State"]
  node_core_crypto["Core Cryptography"]
  node_notes["Confidential Notes<br/>[note.rs]"]
  node_compliance["Compliance Objects<br/>[compliance.rs]"]
  node_callbacks["Callback Workflow<br/>[zk_object.rs]"]
  node_merkle["Merkle Structures"]
  node_state_manager["State Manager<br/>[state_manager.rs]"]
  node_state_roots[("Protocol State<br/>[types.rs]")]
end

subgraph group_server["Server Processing"]
  node_verifier["Deterministic Verifier<br/>[server_verifier.rs]"]
end

node_user(("Protocol Client"))

node_user -->|"initiates"| node_api_client
node_api_client -->|"constructs proofs"| node_circuit_suite
node_circuit_suite -->|"uses constraints"| node_circuit_gadgets
node_circuit_suite -->|"uses primitives"| node_core_crypto
node_api_client -->|"submits proofs"| node_http_api
node_http_api -->|"forwards proof"| node_verifier
node_verifier -->|"verifies proof"| node_circuit_suite
node_verifier -->|"replays operations"| node_state_manager
node_state_manager -->|"updates trees"| node_merkle
node_state_manager -->|"updates roots"| node_state_roots
node_state_manager -->|"tracks commitments"| node_notes
node_circuit_suite -->|"proves note transitions"| node_notes
node_circuit_suite -->|"proves policy"| node_compliance
node_circuit_suite -->|"checks callbacks"| node_callbacks
node_circuit_suite -->|"proves tree operations"| node_merkle
node_verifier -->|"recomputes state"| node_state_roots
node_user -->|"queries state"| node_api_client
node_api_client -->|"requests roots and proofs"| node_http_api
node_circuit_suite -->|"uses setup"| node_proof_setup

click node_api_client "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-api/src/client.rs"
click node_http_api "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-api/src/api.rs"
click node_circuit_suite "https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-circuits/src"
click node_circuit_gadgets "https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-circuits/src/gadgets"
click node_proof_setup "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-circuits/src/setup.rs"
click node_core_crypto "https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-core/src/crypto"
click node_notes "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/note.rs"
click node_compliance "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/compliance.rs"
click node_callbacks "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/zk_object.rs"
click node_merkle "https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-core/src/merkle"
click node_state_manager "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/state_manager.rs"
click node_verifier "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/server_verifier.rs"
click node_state_roots "https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/types.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_api_client,node_http_api,node_user toneBlue
class node_circuit_suite,node_circuit_gadgets,node_proof_setup toneAmber
class node_core_crypto,node_notes,node_compliance,node_callbacks,node_merkle,node_state_manager,node_state_roots toneMint
class node_verifier toneRose
```

## Components

### Client Interface

- [API Client](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-api/src/client.rs): `fluxe-api/src/client.rs`
- [HTTP API](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-api/src/api.rs): `fluxe-api/src/api.rs`

### Proof Construction

- [Transition Circuits](https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-circuits/src): `fluxe-circuits/src`
- [ZK Gadgets](https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-circuits/src/gadgets): `fluxe-circuits/src/gadgets`
- [Proof Setup](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-circuits/src/setup.rs): `fluxe-circuits/src/setup.rs`

### Protocol State

- [Core Cryptography](https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-core/src/crypto): `fluxe-core/src/crypto`
- [Confidential Notes](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/note.rs): `fluxe-core/src/data_structures/note.rs`
- [Compliance Objects](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/compliance.rs): `fluxe-core/src/data_structures/compliance.rs`
- [Callback Workflow](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/data_structures/zk_object.rs): `fluxe-core/src/data_structures/zk_object.rs`
- [Merkle Structures](https://github.com/fluxepay/fluxe/tree/feat/arkworks-0.5.0/fluxe-core/src/merkle): `fluxe-core/src/merkle`
- [State Manager](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/state_manager.rs): `fluxe-core/src/state_manager.rs`
- [Protocol State](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/types.rs): `fluxe-core/src/types.rs`

### Server Processing

- [Deterministic Verifier](https://github.com/fluxepay/fluxe/blob/feat/arkworks-0.5.0/fluxe-core/src/server_verifier.rs): `fluxe-core/src/server_verifier.rs`

### Other components

- **Protocol Client**

## Connections

- Protocol Client → API Client: initiates
- API Client → Transition Circuits: constructs proofs
- Transition Circuits → ZK Gadgets: uses constraints
- Transition Circuits → Core Cryptography: uses primitives
- API Client → HTTP API: submits proofs
- HTTP API → Deterministic Verifier: forwards proof
- Deterministic Verifier → Transition Circuits: verifies proof
- Deterministic Verifier → State Manager: replays operations
- State Manager → Merkle Structures: updates trees
- State Manager → Protocol State: updates roots
- State Manager → Confidential Notes: tracks commitments
- Transition Circuits → Confidential Notes: proves note transitions
- Transition Circuits → Compliance Objects: proves policy
- Transition Circuits → Callback Workflow: checks callbacks
- Transition Circuits → Merkle Structures: proves tree operations
- Deterministic Verifier → Protocol State: recomputes state
- Protocol Client → API Client: queries state
- API Client → HTTP API: requests roots and proofs
- Transition Circuits → Proof Setup: uses setup