# everythingelsewasalreadytaken/fabulous architecture

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

- Interactive diagram: https://gitdiagram.com/everythingelsewasalreadytaken/fabulous
- Repository: https://github.com/everythingelsewasalreadytaken/fabulous

## Overview

##### Project type and purpose
- Project type: A Python-based toolchain (library + CLI + API) for generating custom embedded FPGA fabrics.
- Purpose:
- Fabric architectures via CSV templates and Python objects.
- Generate HDL (Verilog/VHDL) models of those fabrics.
- Invoke external CAD tools (YosysHQ, nextpnr) for bitstream generation and post-fabrication test.
- Provide a user-friendly CLI shell and a Python API for integration or scripting.

##### File structure
- Top-level:
- FABulous/ — core source code
- docs/ — documentation sources
- tests/ — unit and integration tests
- fab­ric_files/ — HDL/VHDL project templates
- .github/ — CI checks, container preparation
- Dockerfile, pyproject.toml, requirements.txt
- Inside FABulous/:
- FABulous_CLI/ — command-line interface modules (shell, synthesis commands, helpers)
- FABulous_API.py — high-level Python API entry points
- FABulous.py — core engine orchestration
- fabric_definition/ — data classes for Bel, Tile, SuperTile, Wire, Fabric, etc.
- geometry_generator/ — compute placement & routing geometry
- fabric_generator/ — parse definitions, generate HDL code (Verilog/VHDL), deal with file creation
- fabric_cad/ — bit-gen and nextpnr model generation (invokes npnr via Python)
- fabric_files/ — stock FPAG templates for user projects in CSV, tcl, Verilog/VHDL
- Configuration & metadata:
- .FABulous/ folder (per project metadata, autogenerated)
- Dockerfile and GitHub Actions YAML for building docs, black formatting, CI testing

##### README for additional insights
- Front-end shell/API → fabric definition loader → fabric generator → external CAD (Yosys, nextpnr) → test harness
- Emphasizes modularity: templates + custom blocks
- Supports both CLI-driven interactive flow and TCL scripts

##### Detail is crucial
- .FABulous metadata folder to show where state is kept.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Shell"]:::internal
        API["Python API"]:::internal
    end

    %% Core Engine
    subgraph "Core Engine"
        Core["Core Engine Orchestrator"]:::internal
    end

    %% Domain Modules
    subgraph "Domain Modules"
        subgraph "Fabric Definition"
            FD["Fabric Definition"]:::internal
        end
        subgraph "Geometry Generator"
            GG["Geometry Generator"]:::internal
        end
        subgraph "Fabric Generator"
            FG["Fabric Generator"]:::internal
        end
        subgraph "Fabric CAD Integration"
            CAD["Fabric CAD Integration"]:::internal
        end
    end

    %% Templates
    subgraph "Template Repositories"
        TF["Template Repo"]:::template
    end

    %% External Tools
    subgraph "External Tools"
        YOS["YosysHQ"]:::external
        NPNR["nextpnr-generic"]:::external
        ICARUS["Icarus Verilog"]:::external
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        HDL["Generated HDL"]:::artifact
        BIT["Bitstream Files"]:::artifact
        TB["Simulation Testbenches"]:::artifact
        META[".FABulous Metadata"]:::artifact
    end

    %% Connections
    CLI -->|"invoke commands"| Core
    API -->|"invoke API"| Core

    Core -->|"load_csv() → model objects"| FD
    Core -->|"compute geometry"| GG
    Core -->|"generate_hdl()"| FG
    Core -->|"run CAD flow"| CAD

    FG -->|"read templates"| TF
    FG -->|"output HDL"| HDL

    CAD -->|"spawn subprocess"| YOS
    CAD -->|"spawn subprocess"| NPNR
    CAD -->|"run simulation"| ICARUS

    YOS -->|"produce reports"| BIT
    NPNR -->|"generate bitstream"| BIT
    ICARUS -->|"produce test benches"| TB

    Core -->|"save state"| META

    %% Click Events
    click CLI "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/FABulous_CLI/"
    click CLI "https://github.com/everythingelsewasalreadytaken/fabulous/blob/FABulous2.0-development/FABulous/FABulous_CLI/FABulous_CLI.py"
    click API "https://github.com/everythingelsewasalreadytaken/fabulous/blob/FABulous2.0-development/FABulous/FABulous_API.py"
    click Core "https://github.com/everythingelsewasalreadytaken/fabulous/blob/FABulous2.0-development/FABulous/FABulous.py"
    click FD "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/fabric_definition/"
    click GG "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/geometry_generator/"
    click FG "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/fabric_generator/"
    click CAD "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/fabric_cad/"
    click TF "https://github.com/everythingelsewasalreadytaken/fabulous/tree/FABulous2.0-development/FABulous/fabric_files/"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef template fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef external fill:#FFEFD5,stroke:#D9822B,color:#D9822B;
    classDef artifact fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
