Update README and removed old docs files (#118)

Author: marcosfrenkel

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing Guide
+
+> [!NOTE]
+> The following is more how to setup your dev environment than a proper contribution guide. Feel free to fork the repo and open a PR. A proper contribution guide is in the works 🚧 
+
+## Development Instructions
+
+1. Install [uv](https://docs.astral.sh/uv/), which will handle project management
+
+1. Clone and navigate into this repository
+
+1. Install the dependencies and set up the virtual environment 🏗️
+
+   ```sh
+   uv sync
+   ```
+
+1. Run the code 🚀
+
+   ```sh
+   uv run pqn
+   ```
+
+### Project Management
+
+A few of the most useful uv commands are shown below.
+See the [uv project guide](https://docs.astral.sh/uv/guides/projects) for more information about working on projects with uv.
+
+- `uv add` -- Add dependencies to the project
+- `uv remove` -- Remove dependencies from the project
+- `uv sync` -- Update the project's environment
+- `uv run` -- Run a command or script
+
+> [!IMPORTANT]
+> Instead of `pip install <package>`, use `uv add <package>`.
+
+### Scripts
+
+To run your code, or a command that is aware of your project environment, use the following command:
+
+- `uv run` -- Run a command or script
+
+See the [script documentation](https://docs.astral.sh/uv/guides/scripts/) for more information.
+
+### Linting and Formatting
+
+Use [Ruff](https://docs.astral.sh/ruff/) to lint and format your code.
+It is already specified as a development dependency in this template's `pyproject.toml`, and is automatically installed when you run `uv sync`.
+
+You can run the linter with `uv run ruff check` (use the `--fix` flag to apply fixes), and the formatter with `uv run ruff format`.
+There are many options available to customize which linting rules are applied.
+All rules are enabled by default, and I have disabled a few redundant ones as a starting point in the `pyproject.toml`.
+Feel free to modify the list as needed for your project.
+See the [documentation](https://docs.astral.sh/ruff/tutorial/) or command help output for additional information.
+
+### Type Checking
+
+Use [mypy](https://www.mypy-lang.org/) for type checking: `uv run mypy`.
+
+### Testing
+
+Use [pytest](https://docs.pytest.org/en/stable/) to run tests:
+
+- `uv run pytest`
+- Use `uv run pytest --cov` to check code coverage.
+
+### Alternate Manual Setup
+
+If it is not possible to use uv for installation, there is a workaround using `virtualenv` and `pip`.
+
+> [!IMPORTANT]
+> This method is intended as a workaround **only** for situations where uv is not available, and **only for local installations** rather than for active project development.
+
+From the root directory of the repository:
+
+1. Create the virtual environment
+
+   ```sh
+   virtualenv .venv
+   ```
+
+1. Activate the virtual environment
+
+   ```sh
+   source .venv/bin/activate
+   ```
+
+1. Install the project dependencies
+
+   ```sh
+   pip install -e .
+   ```
+
+1. Run the code
+
+   ```sh
+   pqn
+   ```
+
+### Possible Problems
+
+What to try if things don't seem to be working:
+
+- Remove the `.venv/` directory and try again ♻️

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Public Quantum Network
+Copyright (c) 2025 Public Quantum Network
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,103 +1,137 @@
-# Public Quantum Network
+# PQN Stack
 
-Software for Public Quantum Network nodes.
+**Software stack for Public Quantum Network (PQN) nodes**
 
-## Development Instructions
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 
-1. Install [uv](https://docs.astral.sh/uv/), which will handle project management
+A distributed node based approach to quantum networks. This repository hosts all the code necessary to make nodes of the PQN function (except for the frontend located [here](https://github.com/PublicQuantumNetwork/pqn-gui)).
 
-1. Clone and navigate into this repository
 
-1. Install the dependencies and set up the virtual environment 🏗️
+<p align="center">
+  <img src="docs/images/frontend_screenshot.png" alt="PQN Web Interface" width="800"/>
+  <br>
+  <em>PQN web interface for public interaction with a quantum network</em>
+</p>
 
-   ```sh
-   uv sync
-   ```
+> [!WARNING]
+> **Early Development**: This package is in early stages of development. APIs, installation procedures, and distribution methods are subject to change. Use in production environments is not recommended at this time.
 
-1. Run the code 🚀
+## Node Architecture
 
-   ```sh
-   uv run pqn
-   ```
+<p align="center">
+  <img src="docs/images/network_architecture.png" alt="PQN Node Architecture" width="800"/>
+  <br>
+  <em>PQN web interface for monitoring and controlling quantum network nodes</em>
+</p>
 
-### Project Management
+Our Node is composed of multiple components. All components inside a node are part of an in internal intranet with no external world access except for quantum links to other hardware or the _Node API_.
 
-A few of the most useful uv commands are shown below.
-See the [uv project guide](https://docs.astral.sh/uv/guides/projects) for more information about working on projects with uv.
+* **Node API**: FastAPI based, handles communications with web-ui as well as Node to Node communication. Only component in a Node than can talk to other components and the outside world. Resides in [src/pqnstack/app/main.py](https://github.com/PublicQuantumNetwork/pqn-stack/blob/master/src/pqnstack/app/main.py).
+* **Lightweight Web UI**: Designed for the general public to be able to interact with quantum networks. Resides in its own repository [here](https://github.com/PublicQuantumNetwork/pqn-gui).
+* **Router**: Routes messages between _Hardware Providers_, PQN developers and _Node APIs_. Uses ZMQ sockets to communicate between machines. Resides in [src/pqnstack/network/router.py](https://github.com/PublicQuantumNetwork/pqn-stack/blob/master/src/pqnstack/network/router.py).
+* **Hardware Provider**: Hosts hardware resources that are provided to whoever needs them inside a Node through the use of ProxyInstruments. Resides in [src/pqnstack/network/instrument_provider.py](https://github.com/PublicQuantumNetwork/pqn-stack/blob/master/src/pqnstack/network/instrument_provider.py).
 
-- `uv add` -- Add dependencies to the project
-- `uv remove` -- Remove dependencies from the project
-- `uv sync` -- Update the project's environment
-- `uv run` -- Run a command or script
+## Quick Start
 
-> [!IMPORTANT]
-> Instead of `pip install <package>`, use `uv add <package>`.
+> [!NOTE]
+> **Hardware Requirements**: To do anything interesting with this software currently requires real quantum hardware components (TimeTagger, rotators, etc.). We are actively working on fully simulated hardware components to enable single-machine demos without physical devices, but this capability is not yet available.
 
-### Scripts
+### Prerequisites
 
-To run your code, or a command that is aware of your project environment, use the following command:
+- Python 3.12 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+- Quantum hardware components (TimeTagger, compatible instruments)
 
-- `uv run` -- Run a command or script
+### Installation
 
-See the [script documentation](https://docs.astral.sh/uv/guides/scripts/) for more information.
+1. **Clone the repository**
 
-### Linting and Formatting
+   ```bash
+   git clone https://github.com/PublicQuantumNetwork/pqn-stack.git
+   cd pqn-stack
+   ```
 
-Use [Ruff](https://docs.astral.sh/ruff/) to lint and format your code.
-It is already specified as a development dependency in this template's `pyproject.toml`, and is automatically installed when you run `uv sync`.
+2. **Install dependencies**
 
-You can run the linter with `uv run ruff check` (use the `--fix` flag to apply fixes), and the formatter with `uv run ruff format`.
-There are many options available to customize which linting rules are applied.
-All rules are enabled by default, and I have disabled a few redundant ones as a starting point in the `pyproject.toml`.
-Feel free to modify the list as needed for your project.
-See the [documentation](https://docs.astral.sh/ruff/tutorial/) or command help output for additional information.
+   ```bash
+   uv sync
+   
+   # Or sync with the --extra flag to run the full node
+   uv sync --extra webapp
+   ```
 
-### Type Checking
+### Starting a Node
 
-Use [mypy](https://www.mypy-lang.org/) for type checking: `uv run mypy`.
+To fully start a PQN Node, you need to initialize 4 different processes:
 
-### Testing
+* **Node API**
+* **Router**
+* **Hardware provider** (optional)
+* **Web GUI** (optional)
 
-Use [pytest](https://docs.pytest.org/en/stable/) to run tests:
+### Node API
 
-- `uv run pytest`
-- Use `uv run pytest --cov` to check code coverage.
+#### Config file
 
-### Alternate Manual Setup
+Before starting a Node API, you need to set up a configuration file:
+
+1. **Copy the example configuration:**
+   ```bash
+   cp configs/config_app_example.toml config.toml
+   ```
 
-If it is not possible to use uv for installation, there is a workaround using `virtualenv` and `pip`.
+2. **Edit the configuration:**
+   Open `config.toml` in your editor and replace the placeholder values with your actual settings (router addresses, instrument names, etc.).
 
 > [!IMPORTANT]
-> This method is intended as a workaround **only** for situations where uv is not available, and **only for local installations** rather than for active project development.
+> The configuration file **must** be named `config.toml` and placed at the root of the repository. If you use a different name or location, the API will not be able to find it.
 
-From the root directory of the repository:
+#### Run the FastAPI instance
+For a quick run you can simply run to get started:
 
-1. Create the virtual environment
+```bash
+   uv run fastapi run src/pqnstack/app/main.py
+```
 
-   ```sh
-   virtualenv .venv
-   ```
+Please take a look at the [FastAPI docs](https://fastapi.tiangolo.com/deployment/) for more options on how to run the API
 
-1. Activate the virtual environment
+### Router and Hardware Provider
 
-   ```sh
-   source .venv/bin/activate
-   ```
+Both the Router and Hardware Provider can be configured in two ways:
 
-1. Install the project dependencies
+1. **Using CLI flags** - Pass configuration directly as command-line arguments
+2. **Using a config file** - Use the `--config` flag with a path to a TOML configuration file (see example in [configs/config_messaging_example.toml](https://github.com/PublicQuantumNetwork/pqn-stack/blob/master/configs/config_messaging_example.toml))
 
-   ```sh
-   pip install -e .
-   ```
+The config file can contain settings for both router and provider:
+- Router settings go under `[router]`
+- Provider settings go under `[provider]` with instruments defined as `[[provider.instruments]]`
 
-1. Run the code
+Command-line arguments override config file settings.
 
-   ```sh
-   pqn
-   ```
+#### Starting the Router
+
+```bash
+# Using CLI flags
+uv run pqn start-router --name router1 --host localhost --port 5555
+
+# Using a config file
+uv run pqn start-router --config configs/config_messaging_example.toml
+```
+
+#### Starting an Instrument Provider
+
+```bash
+# Using a config file (recommended for defining instruments)
+uv run pqn start-provider --config configs/config_messaging_example.toml
 
-### Possible Problems
+# Using CLI flags with inline JSON for instruments
+uv run pqn start-provider \
+  --name provider1 \
+  --router-name router1 \
+  --instruments '{"dummy1": {"import": "pqnstack.pqn.drivers.dummies.DummyInstrument", "desc": "Test Instrument", "hw_address": "123456"}}'
+```
 
-What to try if things don't seem to be working:
+### Web GUI
 
-- Remove the `.venv/` directory and try again ♻️
+For instructions on how install and start the web GUI please see the repo where it lives at [https://github.com/PublicQuantumNetwork/pqn-gui](https://github.com/PublicQuantumNetwork/pqn-gui)

configs/config_app_example.toml

@@ -5,6 +5,9 @@ router_name = "router1"
 router_address = "xx.xx.xx.xx"  # Replace with actual IP address
 router_port = 5555
 
+# Rotary encoder serial adress
+rotary_encoder_address = "/dev/tty.usbmodem1101"
+
 # Timetagger configuration (provider_name, instrument_name)
 timetagger = ["provider", "tagger"] # Replace with actual provider and instrument names