# lolzio5/jabbal architecture

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

- Interactive diagram: https://gitdiagram.com/lolzio5/jabbal
- Repository: https://github.com/lolzio5/jabbal

## Overview

##### Project type and purpose
- This is a hardware-accelerated full-stack system for simulating Conway’s Game of Life at very high frame rates.
- It combines three domains:
- Software UI on a laptop (hand-gesture detection and control)
- A PYNQ-Z1 board running Python/Jupyter to orchestrate the FPGA overlay
- FPGA logic (written in SystemVerilog) to compute next generations and drive an HDMI-out display.

##### File structure
- Top level:
- UI/hand_detection → Python scripts and Keras model for detecting gestures.
- Notebooks → PYNQ Jupyter notebooks to load overlays and send commands to FPGA.
- Generated bit and hwh files → prebuilt FPGA bitstream and hardware description for PYNQ.
- SystemVerilog & VerilogSource → hardware source code for next-state logic, line buffers, etc.
- PythonGameofLife & C++GameOfLife → CPU-only reference implementations (fallbacks/benchmarks).
- Testbenches → verification suites for the SystemVerilog modules (development artifacts).

##### README for insights
- Describes a client-server interaction:
- PYNQ loads the bitstream into the FPGA, writes the initial pattern, steps the hardware accelerator, and streams video frames over HDMI.
- Hardware toolchain: Vivado → generates .bit/.hwh → loaded by PYNQ Python API.

##### Detail
- Every major block: client app, network link, server, overlay loader, memory, compute pipeline, video out.
- Don’t over-abstract—show separate modules in the FPGA overlay (line_buffer, parallel_next_state, single_next_state, pixel_generator).
- Configuration flows (Vivado → .bit/.hwh → PYNQ API).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Client Layer
    subgraph "UI Client (Laptop)"
        direction TB
        HD["Hand-Detection Module"]:::software
        SC["Network Socket Client"]:::software
    end

    %% PYNQ Server Layer
    subgraph "PYNQ Server (PYNQ-Z1 Board)"
        direction TB
        NB["Jupyter Notebook Interface"]:::software
        Loader["PYNQ Overlay Loader"]:::software
        BIT["FPGA Bitstream (.bit)"]:::software
        HWH["Hardware HWH (.hwh)"]:::software
    end

    %% FPGA Overlay Layer
    subgraph "FPGA Overlay"
        direction TB
        BRAM["Block RAM (Grid State)"]:::hardware
        LS["Line Buffer"]:::hardware
        PNS["Parallel Next-State"]:::hardware
        SNS["Single Next-State"]:::hardware
        Pixel["Pixel Generator"]:::hardware
        Mode["Mode Selector"]:::hardware
        HDMI["HDMI Controller"]:::hardware
    end

    %% Monitor
    Mon["Monitor (HDMI Display)"]:::external

    %% Fallback Simulation Engines
    subgraph "Fallback Engines"
        direction TB
        PyStd["PythonGameOfLife Standard"]:::fallback
        PyP1["PythonGameOfLife Parallel v1"]:::fallback
        PyP2["PythonGameOfLife Parallel v2"]:::fallback
        PyP3["PythonGameOfLife Parallel v3"]:::fallback
        CppStd["C++ GameOfLife"]:::fallback
        CppPar["C++ GameOfLife Parallel"]:::fallback
    end

    %% Connections
    HD -->|"gesture data"| SC
    SC -->|"TCP socket"| NB
    NB -->|"load overlay"| Loader
    Loader -->|"uses"| BIT
    Loader -->|"uses"| HWH
    NB -->|"MMIO write initial grid"| BRAM
    NB -->|"MMIO start/stop"| SNS
    BRAM --> LS
    LS --> PNS
    PNS --> SNS
    SNS --> Pixel
    Pixel --> HDMI
    HDMI -->|"HDMI video"| Mon

    %% Optional fallback paths
    NB -->|"fallback"| PyStd
    NB -->|"fallback"| PyP1
    NB -->|"fallback"| PyP2
    NB -->|"fallback"| PyP3
    NB -->|"fallback"| CppStd
    NB -->|"fallback"| CppPar

    %% Click Events
    click HD "https://github.com/lolzio5/jabbal/tree/main/UI/hand_detection/"
    click SC "https://github.com/lolzio5/jabbal/blob/main/UI/hand_detection/client.py"
    click NB "https://github.com/lolzio5/jabbal/tree/main/Notebooks/"
    click BIT "https://github.com/lolzio5/jabbal/blob/main/Generated bit and hwh files/base15A.bit"
    click HWH "https://github.com/lolzio5/jabbal/blob/main/Generated bit and hwh files/base15A.hwh"
    click BRAM "https://github.com/lolzio5/jabbal/blob/main/SystemVerilog/block_ram.v"
    click LS "https://github.com/lolzio5/jabbal/blob/main/VerilogSource/V2/line_buffer.v"
    click PNS "https://github.com/lolzio5/jabbal/blob/main/VerilogSource/V2/parallel_next_state.v"
    click SNS "https://github.com/lolzio5/jabbal/blob/main/VerilogSource/V2/single_next_state.v"
    click Pixel "https://github.com/lolzio5/jabbal/blob/main/VerilogSource/V2/pixel_generator.v"
    click Mode "https://github.com/lolzio5/jabbal/blob/main/Testbenches/Updated project/V4.1/mode_selector.v"
    click PyStd "https://github.com/lolzio5/jabbal/blob/main/PythonGameofLife/Standard/main.py"
    click PyP1 "https://github.com/lolzio5/jabbal/blob/main/PythonGameofLife/Parallel_v1/main.py"
    click PyP2 "https://github.com/lolzio5/jabbal/blob/main/PythonGameofLife/Parallel_v2/main.py"
    click PyP3 "https://github.com/lolzio5/jabbal/blob/main/PythonGameofLife/Parallel_v3/main.py"
    click CppStd "https://github.com/lolzio5/jabbal/blob/main/C++GameOfLife/GameOfLife.cpp"
    click CppPar "https://github.com/lolzio5/jabbal/blob/main/C++GameOfLife/GameOfLifeParallel.cpp"

    %% Styles
    classDef software fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef hardware fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef fallback fill:#f2f2f2,stroke:#333,stroke-width:1px
```
