# mazinlab/mkidgen3 architecture

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

- Interactive diagram: https://gitdiagram.com/mazinlab/mkidgen3
- Repository: https://github.com/mazinlab/mkidgen3

## Overview

To accurately capture the architecture of MKIDGen3 and guide your diagramming effort, follow these tailored steps.

##### Project type and purpose
- This is a mixed embedded-hardware and Python software system for RF-multiplexed MKID readout.
- It comprises:
- A host-side Python “client” (CLI, Jupyter notebooks, plotting)
- A networked Python “server” running on a PYNQ-Linux RFSoC board
- FPGA gateware/HLS overlay (built separately in gen3-vivado-top)
- Physical RFSoC hardware (DAC/ADC/PLL), an IF board, and external test equipment

##### File structure
- Top-level directories:
- firmware/  – Vivado/HLS gateware (external repo)
- mkidgen3/ – Python package: drivers, server, client utilities, config loaders, plotting
- scripts/  – helper scripts for array setup, sweeps, testing
- notebooks/– Jupyter notebooks driving experiment flows
- arduino/  – C++ libraries (ArduinoJson, OneWire, SdFat) for IF-board microcontrollers
- config/   – udev rules, hardware config files
- Key config/build files: pyproject.toml, README.md, mkidgen3/config/*.yaml/.txt

##### README for insights
- Emphasizes a Python client/server model over Ethernet to the RFSoC board
- Relies on PYNQ environment, patched xrfdc driver, and bitstream built in a separate repo
- Installation groups: [client, plotting] on host; [server, plotting] on the board

##### Main components and their interactions
a. Host-side components:
- CLI & Jupyter notebooks (scripts in notebooks/, mkidgen3.plotting)
- mkidgen3.client modules (e.g., feedline_client.py)
- Configuration files (mkidgen3/config/*.yaml)
b. Network layer:
- TCP/ZeroMQ or simple socket RPC between feedline_client and feedline_server
c. Board-side Python server:
- mkidgen3.server package: feedline_server, aggregator, captures, fpga_objects
- Uses overlay_helpers to load the FPGA bitstream and map AXI-registers/fifos
d. Driver abstraction layer:
- mkidgen3.drivers: Python wrappers around hardware blocks (axi-fifo, dactable, ddc, etc.)
- mkidgen3.equipment_drivers: instrument control (e.g., Anritsu signal source)
e. FPGA overlay & gateware:
- Vivado-built HLS/RTL IP blocks (in firmware repo) providing DDC, FFT, phase match, etc.
- Exposed via PYNQ overlay into Python through FPGAObjects
f. Physical hardware:
- RFSoC ZCU111 (DAC → mixers → IF board → detectors → ADC back into FPGA)
- External instruments controlled via Ethernet or serial

##### Architectural patterns & design principles
- Client–server separation: clear host vs. board responsibilities
- Layered hardware abstraction: drivers hide register-level details
- Modular design: each driver or server piece is a standalone Python module
- Configuration-driven: YAML/TXT files drive register values and sweep parameters

## Diagram (Mermaid)

```mermaid
graph TD
  %% Host PC Layer
  subgraph "Host PC" 
    direction TB
    NB["Jupyter Notebooks"]:::config
    CLI["CLI Scripts"]:::frontend
    Client["feedline_client.py"]:::frontend
    Plot["Plotting Utilities"]:::frontend
    Conf["Config Files"]:::config
  end

  %% Network Layer
  subgraph "Network/Ethernet"
    direction TB
    NET["TCP/ZeroMQ RPC"]:::network
  end

  %% PYNQ Linux (RFSoC Board)
  subgraph "PYNQ Linux (RFSoC Board)"
    direction TB
    FS["feedline_server.py"]:::backend
    AGG["aggregator.py"]:::backend
    CAP["captures.py"]:::backend
    FPGAObj["fpga_objects.py"]:::backend
    MISC["misc.py"]:::backend
    PT["photontable.py"]:::backend
    PM["pixelmap.py"]:::backend
    WF["waveform.py"]:::backend
    OH["overlay_helpers.py"]:::backend
    subgraph "Driver Abstraction Layer"
      direction TB
      DR1["axififo.py"]:::drivers
      DR2["axiswitch.py"]:::drivers
      DR3["bintores.py"]:::drivers
      DR4["capture.py"]:::drivers
      DR5["dactable.py"]:::drivers
      DR6["ddc.py"]:::drivers
      DR7["ddssweep.py"]:::drivers
      DR8["ifboard.py"]:::drivers
      DR9["iqgen.py"]:::drivers
      DR10["mcdma.py"]:::drivers
      DR11["phasematch.py"]:::drivers
      DR12["ppssync.py"]:::drivers
      DR13["rfdc.py"]:::drivers
      DR14["rfdcclock.py"]:::drivers
      DR15["trigger.py"]:::drivers
    end
    subgraph "Equipment Drivers"
      direction TB
      EQ1["anritsu.py"]:::drivers
      EQ2["ifboard.py"]:::drivers
    end
    subgraph "MKID Setup Utilities"
      direction TB
      MU1["interactive_setup.py"]:::backend
      MU2["loop_locator.py"]:::backend
      MU3["sweeps.py"]:::backend
    end
    subgraph "Core Utilities"
      direction TB
      CU1["fixedpoint.py"]:::backend
      CU2["registers.py"]:::backend
      CU3["system_parameters.py"]:::backend
    end
  end

  %% FPGA Overlay Layer
  subgraph "FPGA Overlay (Vivado/HLS IP)" 
    direction TB
    HLS["HLS/RTL IP Blocks"]:::fpga
  end

  %% Physical RF Chain
  subgraph "Physical RF Chain"
    direction TB
    RFHW["RFSoC ZCU111 Hardware"]:::hardware
    IFHW["IF Board"]:::hardware
    EXT["External Instruments"]:::hardware
  end

  %% Connections
  NB -->|"uses client"| Client
  CLI -->|"invokes client"| Client
  Client -->|"RPC"| NET
  NET -->|"RPC"| FS
  Conf -->|"loads"| Client
  Conf -->|"loads"| FS
  Plot -->|"plots via client"| Client
  Plot -->|"plots via server"| FS

  FS -->|"aggregates"| AGG
  AGG --> CAP
  CAP --> FPGAObj
  FPGAObj --> OH
  OH --> HLS

  FS --> DR1
  FS --> DR6
  FS --> DR13

  DR1 --> HLS
  DR6 --> HLS
  DR13 --> HLS

  EQ1 --> FS
  EQ2 --> FS

  MU1 --> FS
  MU2 --> FS
  MU3 --> FS

  CU1 --> FS
  CU2 --> FS
  CU3 --> FS

  HLS -->|"AXI Stream / AXI-Lite"| RFHW
  RFHW -->|"RF signal"| IFHW
  IFHW -->|"detector output"| HLS
  EXT --> FS

  %% Click Events
  click Client "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/feedline_client.py"
  click Plot "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/plotting.py"
  click NB "https://github.com/mazinlab/mkidgen3/tree/main/notebooks/"
  click Conf "https://github.com/mazinlab/mkidgen3/tree/main/mkidgen3/config/"
  click FS "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/feedline_server.py"
  click OH "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/overlay_helpers.py"
  click AGG "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/aggregator.py"
  click CAP "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/captures.py"
  click FPGAObj "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/fpga_objects.py"
  click MISC "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/misc.py"
  click PT "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/photontable.py"
  click PM "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/pixelmap.py"
  click WF "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/server/waveform.py"
  click DR1 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/axififo.py"
  click DR2 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/axiswitch.py"
  click DR3 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/bintores.py"
  click DR4 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/capture.py"
  click DR5 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/dactable.py"
  click DR6 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/ddc.py"
  click DR7 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/ddssweep.py"
  click DR8 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/ifboard.py"
  click DR9 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/iqgen.py"
  click DR10 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/mcdma.py"
  click DR11 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/phasematch.py"
  click DR12 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/ppssync.py"
  click DR13 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/rfdc.py"
  click DR14 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/rfdcclock.py"
  click DR15 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/drivers/trigger.py"
  click EQ1 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/equipment_drivers/anritsu.py"
  click EQ2 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/equipment_drivers/ifboard.py"
  click MU1 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/mkid_setup/interactive_setup.py"
  click MU2 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/mkid_setup/loop_locator.py"
  click MU3 "https://github.com/mazinlab/mkidgen3/blob/main/mkidgen3/mkid_setup/sweeps.py"

  %% Styles
  classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
  classDef backend fill:#6cf,stroke:#333,stroke-width:1px
  classDef config fill:#f96,stroke:#333,stroke-width:1px
  classDef network fill:#6f9,stroke:#333,stroke-width:1px
  classDef drivers fill:#ccf,stroke:#333,stroke-width:1px
  classDef fpga fill:#c9f,stroke:#333,stroke-width:1px
  classDef hardware fill:#aaa,stroke:#333,stroke-width:1px
```
