# supersodasea/plugcat architecture

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

- Interactive diagram: https://gitdiagram.com/supersodasea/plugcat
- Repository: https://github.com/supersodasea/plugcat

## Overview

Based on our analysis, this project—named “Plugcat”—is a multi-disciplinary hardware design repository that integrates PCB/physical board design with digital logic design for an HDMI output system. The project includes KiCad files for the physical board (in the QSFP-HDMI-OUT-NB7NQ621M folder), digital design sources written in both Chisel (Scala) and Verilog (in the common folder), and FPGA-related materials (Vivado constraints and Tcl scripts) along with example projects for different FPGA boards (e.g., ADM-PCIE-KU3, Alibaba-VU13P, BoChenJingXin-KU5P).

##### Main Components
- Board Design Module: Represented by the QSFP-HDMI-OUT-NB7NQ621M directory. This contains the KiCad schematic (.kicad_sch), PCB layout (.kicad_pcb, .kicad_pro), and additional related files. Also include the 3D printed shell files (STL) under the shell subdirectory.
- HDL and Digital Logic Subsystem: Located primarily in the common/Chisel and common/Verilog directories. Here you have:
- HDMI functional blocks such as “HDMIDataIslandPacket”, “HDMIScramblerLFSR”, “HDMITMDSEncoder”, “HDMISource”, and “VideoGenerator”.
- These modules represent the digital logic to generate HDMI signals, manage video timing, encode TMDS data, and possibly scramble data.
- FPGA Integration/Toolchain Integration: The common/Vivado directory holds constraints (timing, clock, configuration, LED, and QSFP related) and scripts for synthesis, implementation, bitstream generation, and programming. This indicates that Vivado is used for FPGA support.
- Example Projects: The examples folder holds dedicated applications for different target FPGA boards (ADM-PCIE-KU3, Alibaba-VU13P, BoChenJingXin-KU5P). Each example includes build scripts, TCL scripts, IP generation scripts, board-specific constraints, and Verilog sources that instantiate or integrate the HDMI subsystem.

##### Relationships and Interactions
- The digital logic (Chisel/Verilog HDMI modules) forms the core processing and signal generation subsystem.
- This core communicates with the physical layer, implemented on the board designed using KiCad, which includes the QSFP connector handling and HDMI outputs.
- The FPGA toolchain (Vivado scripts and constraints) bridges the digital design with specific hardware targets. It governs how the synthesized design maps to physical pins and meets timing requirements.
- Example projects act as “use-case” integrations that demonstrate how to deploy the design on various hardware platforms by leveraging the core HDMI modules along with board-specific adjustments.

##### Architectural Patterns/Design Principles
- Modularity: The project clearly separates concerns—hardware board layouts, digital logic modules, and FPGA integration are kept in distinct folders.
- Reusability and Extensibility: The “common” directory holds shared modules (Chisel, Verilog, KiCad libraries) that can be reused across different board examples.
- Layered Design: The architecture spans from low-level physical design (PCB, shell) to high-level HDL modules and finally to board-specific implementations and FPGA configurations.
- Toolchain Integration: Clear use of build systems (Mill for Scala/Chisel and build.py scripts for example projects) and FPGA toolchain (Vivado scripts) indicates a well-structured flow from design to deployment.

##### Relevant Technologies, Frameworks, and Libraries
- KiCad for PCB design (schematics, PCB layout, footprint and symbol libraries).
- Chisel (Scala-based HDL) and Verilog for digital logic design, targeting HDMI signal generation.
- Vivado FPGA Design Suite for synthesis, constraints management, and bitstream generation.
- Scripting languages (Python, TCL) for build automation and project generation.
- Possibly integration with simulation or testing frameworks implicit in the build scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HDL Core (Digital Logic)
    subgraph "HDL Core (Digital Logic)"
        hdl_chisel["Chisel HDL (HDMI Modules)"]:::hdl
        hdl_verilog["Verilog HDL (HDMI Modules)"]:::hdl
    end

    %% FPGA Integration / Toolchain
    subgraph "FPGA Integration"
        fpga["Vivado Toolchain (Constraints & Scripts)"]:::fpga
    end

    %% Physical Board Design
    subgraph "Physical Board Design"
        pb_board["PCB Design (KiCad)"]:::physical
        pb_shell["3D Shell Files"]:::physical
    end

    %% Example Projects for FPGA Boards
    subgraph "FPGA Example Projects"
        ex1["ADM-PCIE-KU3 Example"]:::example
        ex2["Alibaba-VU13P Example"]:::example
        ex3["BoChenJingXin-KU5P Example"]:::example
    end

    %% Relationships
    hdl_chisel -->|"drives"| pb_board
    hdl_verilog -->|"drives"| pb_board

    hdl_chisel -->|"synthesized_by"| fpga
    hdl_verilog -->|"synthesized_by"| fpga

    fpga -->|"configures"| pb_board

    fpga -->|"deployed_on"| ex1
    fpga -->|"deployed_on"| ex2
    fpga -->|"deployed_on"| ex3

    pb_board -->|"integrated_in"| ex1
    pb_board -->|"integrated_in"| ex2
    pb_board -->|"integrated_in"| ex3

    %% Click Events
    click pb_board "https://github.com/supersodasea/plugcat/tree/main/QSFP-HDMI-OUT-NB7NQ621M/board"
    click pb_shell "https://github.com/supersodasea/plugcat/tree/main/QSFP-HDMI-OUT-NB7NQ621M/shell"
    click hdl_chisel "https://github.com/supersodasea/plugcat/tree/main/common/Chisel/hdmi"
    click hdl_verilog "https://github.com/supersodasea/plugcat/tree/main/common/Verilog/hdmi"
    click fpga "https://github.com/supersodasea/plugcat/tree/main/common/Vivado"
    click ex1 "https://github.com/supersodasea/plugcat/tree/main/QSFP-HDMI-OUT-NB7NQ621M/examples/ADM-PCIE-KU3"
    click ex2 "https://github.com/supersodasea/plugcat/tree/main/QSFP-HDMI-OUT-NB7NQ621M/examples/Alibaba-VU13P"
    click ex3 "https://github.com/supersodasea/plugcat/tree/main/QSFP-HDMI-OUT-NB7NQ621M/examples/BoChenJingXin-KU5P"

    %% Styles
    classDef hdl fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef fpga fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef physical fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef example fill:#FFB6C1,stroke:#C71585,stroke-width:2px;
```
