From 9a2ec11a4cba4e221b21d611577e87b3e2f48045 Mon Sep 17 00:00:00 2001
From: randogoth <kflux@posteo.de>
Date: Mon, 26 Oct 2026 16:06:05 +0200
Subject: [PATCH] docs: add architecture diagram

---
 README.md          | 30 ++++++++++++++++++++++++++++++
 fpga/src/strix.qsf |  8 ++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0124683..45b01c7 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,36 @@ Entropy comes from FPGA ring oscillators whose sampled timing jitter is XOR-comb
 - Per-second trials in Global Consciousness Project format (200-bit XOR-masked sums per generator, plus full-rate sums), with Stouffer Z and network variance
 - Raw ring captures and frequency measurement for characterization
 
+```mermaid
+flowchart LR
+    subgraph FPGA["FPGA: Cyclone 10 LP, 120 MHz from a PLL on the SAMD21's 48 MHz clock"]
+        direction LR
+        subgraph GEN["4 generators"]
+            direction TB
+            RO["90 ring oscillators<br/>3 taps XORed per ring"] --> SMP["2-flip-flop sampling"]
+            SMP --> SX["spatial XOR<br/>of all rings"]
+            SX --> TX["temporal XOR<br/>of 1-8 bits"]
+        end
+        SMP --> HM["health monitors<br/>repetition count, adaptive<br/>proportion, dead rings"]
+        SX --> HM
+        TX --> SEL["healthy generators<br/>g0-g3 and combined XOR"]
+        HM -->|healthy| SEL
+        SEL --> ST["entropy stream<br/>4 KB FIFO"]
+        SEL --> STATS["statistics<br/>per-trial counts"]
+        SEL --> AMP["bias amplifier<br/>2 paths, 3 stages"]
+        SEL --> GCP["GCP trials<br/>per second"]
+        GEN -.-> CAP["raw capture,<br/>frequency counter"]
+        ST & STATS & AMP & GCP & CAP & HM --> REG["SPI registers"]
+        PT["WiFi module<br/>pin pass-through"]
+    end
+    REG <-->|SPI 8 MHz| MCU["SAMD21 firmware"]
+    MCU <--> PT
+    PT <--> NINA["NINA-W102<br/>WiFi and BLE"]
+    MCU --> USB["USB serial"]
+    NINA --> HTTP["HTTP on its own<br/>access point"]
+    NINA --> BLE["BLE GATT service"]
+```
+
 The USB, HTTP and BLE API is documented in [arduino/strix/API.md](arduino/strix/API.md).
 
 ## Command-line client
diff --git a/fpga/src/strix.qsf b/fpga/src/strix.qsf
index 873072a..80c20c8 100644
--- a/fpga/src/strix.qsf
+++ b/fpga/src/strix.qsf
@@ -48,7 +48,7 @@ set_global_assignment -name MIN_CORE_JUNCTION_TEMP 0
 set_global_assignment -name MAX_CORE_JUNCTION_TEMP 85
 set_global_assignment -name ERROR_CHECK_FREQUENCY_DIVISOR 1
 set_global_assignment -name NOMINAL_CORE_SUPPLY_VOLTAGE 1.2V
-set_global_assignment -name EDA_SIMULATION_TOOL "Questa Intel FPGA (Verilog)"
+set_global_assignment -name EDA_SIMULATION_TOOL "Questa Altera FPGA (Verilog)"
 set_global_assignment -name EDA_TIME_SCALE "1 ps" -section_id eda_simulation
 set_global_assignment -name EDA_OUTPUT_DATA_FORMAT "VERILOG HDL" -section_id eda_simulation
 set_global_assignment -name EDA_GENERATE_FUNCTIONAL_NETLIST OFF -section_id eda_board_design_timing
@@ -310,4 +310,8 @@ set_location_assignment PIN_T7 -to oFLASH_WP
 set_location_assignment PIN_N2 -to oSAM_INT
 set_location_assignment PIN_L16 -to iSAM_INT
 set_instance_assignment -name IO_STANDARD "2.5 V" -to oSAM_INT
-set_instance_assignment -name IO_STANDARD "3.3-V LVCMOS" -to iSAM_INT
\ No newline at end of file
+set_instance_assignment -name IO_STANDARD "3.3-V LVCMOS" -to iSAM_INT
+set_instance_assignment -name PARTITION_HIERARCHY root_partition -to | -section_id Top
+set_global_assignment -name PARTITION_NETLIST_TYPE SOURCE -section_id Top
+set_global_assignment -name PARTITION_FITTER_PRESERVATION_LEVEL PLACEMENT_AND_ROUTING -section_id Top
+set_global_assignment -name PARTITION_COLOR 16764057 -section_id Top
\ No newline at end of file