Architecture#

A PQN node is composed of four main components. All components except the Node API reside in an internal intranet with no external network access.

                        ┌─────────────────────────────────┐
                        │           PQN Node               │
                        │                                  │
  Web UI / Other Nodes ─┤──► Node API (FastAPI)            │
                        │         │                        │
                        │         ▼                        │
                        │      Router (ZMQ)                │
                        │         │                        │
                        │         ▼                        │
                        │  Hardware Provider               │
                        │         │                        │
                        │         ▼                        │
                        │   Quantum Hardware               │
                        └─────────────────────────────────┘

Node API#

File: src/pqnstack/app/main.py

A FastAPI application that is the only component with external network access. It handles:

Communication with the web frontend (pqn-gui)
Node-to-node communication (e.g., for two-node CHSH experiments)
Exposing experiment endpoints

Interactive API docs are available at http://127.0.0.1:8000/docs when the server is running.

Router#

File: src/pqnstack/network/router.py

Routes messages between Hardware Providers, PQN developers, and Node APIs using ZMQ sockets. Required on the first computer in a node; optional for additional computers joining the same node.

Hardware Provider#

File: src/pqnstack/network/instrument_provider.py

Hosts quantum hardware resources and makes them available to other components via ProxyInstruments. Each instrument is loaded from a driver class specified in the config file.

Drivers#

Directory: src/pqnstack/pqn/drivers/

Hardware drivers abstract physical devices:

Driver	Description
`TimeTagger`	Photon detection timing
`Polarimeter`	Photon polarization measurement
`Rotator` / `RotaryEncoder`	Polarization basis rotation (half-wave plates)
`QKD Driver`	Quantum key distribution hardware
`CHSH Driver`	Bell test measurement
`DummyInstrument`	Software-only testing without physical hardware

Protocols#

Directory: src/pqnstack/pqn/protocols/

Experiment protocols implement the quantum measurement logic:

Protocol	File	Description
CHSH	`chsh.py`	Bell inequality test
QKD	`qkd.py`	Quantum key distribution
Tomography	`tomography.py`	Quantum state tomography
Visibility	`visibility.py`	Interference visibility measurement
Measurement	`measurement.py`	Base measurement functionality

CLI#

The pqn CLI (implemented with Typer) provides commands to start each component. See Running a Node for usage.