# ojuliomiguel/snes_pangolin architecture

> Architecture diagram of the GitHub repository ojuliomiguel/snes_pangolin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ojuliomiguel/snes_pangolin
- Repository: https://github.com/ojuliomiguel/snes_pangolin

## Overview

##### What this project is (type + purpose)

This is a **SNES homebrew ROM project** written primarily in **65c816 assembly**, built via a **Makefile** into a `.sfc` ROM image, and run in an emulator (Mesen/Snes9x). The purpose appears to be a “hello world / hello screen” style ROM (“Hello Julio” GIF) with supporting assets (font, palette/tiles).

- **Build toolchain** produces a ROM binary from source + assets + linker configuration.
- **Runtime environment** is the SNES hardware model (emulator/console), executing ROM code and reading embedded assets.

##### How the repository structure maps to architecture

From the file tree:

##### Source (ROM program)
- `src/hello.asm` – likely the main program entry, initialization, and rendering loop.
- `src/test_minimal.asm` – a minimal/test ROM program (sanity check).
- `src/hdr.inc` – SNES ROM header/constants/macros included by ASM sources.
- `src/minimal.cfg`, `src/snes.cfg` – **linker/memory mapping configs** (very important in SNES dev; they define banks, vectors, ROM layout).

##### Assets (data packed into ROM)
- `assets/font.bin` – raw font tile data.
- `assets/cup_16x8_4bpp.bin` – 4bpp graphics tile data.
- `assets/cup_16x8_palette.cgram` – palette data formatted for SNES CGRAM.

##### Build & dev workflow
- `Makefile` – orchestrates assembling/linking, generating final `.sfc`, copying to root.
- `scripts/run_emulator.sh` – runs the produced ROM in an emulator.
- `scripts/watch.sh` – file-watching rebuild loop.
- `.vscode/*` – VS Code task wiring to the Make targets.
- `font.py` – an **asset pipeline tool** (likely converts source font to SNES tile format).

##### Meta
- `README.md` – workflow and emulator discovery.
- `.github/*`, `.memory/*` – not runtime-critical, but explain contributor/dev context.

##### Developer / IDE
- VS Code Tasks call Make targets.
##### Build Orchestrator
- `Makefile` (targets: build/run/watch/clean).
##### Asset Pipeline
- `font.py` produces `assets/font.bin` (or regenerates it).
- Prebuilt binaries in `assets/` are inputs to ROM link stage.
##### Assembler + Linker (implicit from cfg usage)
- Even if not visible in tree, the presence of `.cfg` strongly implies something like `ca65/ld65` or a similar assembler/linker pair.
- Inputs: `src/*.asm`, `src/hdr.inc`, `assets/*`, `src/*.cfg`
- Output: `build/hello.sfc` and `hello.sfc` (copied to root).
##### Emulator Runner
- `scripts/run_emulator.sh` selects Mesen/Snes9x and launches ROM.

##### ROM image (`hello.sfc`)
- Contains: code + vectors/header + embedded asset data + memory map as defined by `snes.cfg`.
##### SNES CPU (65c816)
- Executes init, main loop, and routines (rendering, DMA transfers, etc.).
##### PPU / Video
- Reads VRAM/CGRAM/OAM state set up by the program.
- Displays tiles/sprites from assets.
##### Memory regions
- ROM banks (mapped by cfg)
- RAM (WRAM)
- VRAM/CGRAM (graphics/palette)
##### External runtime host
- Emulator (Mesen/Snes9x) or real hardware via EverDrive.

- **VS Code Task / CLI** → **Makefile**
- **Makefile** → **(Assembler + Linker)**
- **src/hello.asm**, **src/test_minimal.asm** → **Assembler**
- **src/snes.cfg** / **src/minimal.cfg** → **Linker** (memory map/layout constraints)
- **Linker** → outputs **build/hello.sfc**
- **build/hello.sfc** → copied to **hello.sfc** (root)
- **scripts/run_emulator.sh** consumes **hello.sfc** (or build output) → launches **Emulator**

##### Runtime flow
- **Emulator/Console** loads **ROM**
- **CPU** executes code from ROM → writes to **PPU registers / VRAM / CGRAM**
- **PPU** reads **VRAM/CGRAM** → produces video frame output
- Optional: CPU reads controller input (not shown in repo but often present; include only if code confirms)

##### Architectural patterns/design principles implied here

- **Separation of concerns:**
- `src/` = program logic + platform headers
- `assets/` = binary data inputs
- `scripts/` = dev tooling
- `*.cfg` = explicit memory/ROM layout configuration
- **“Embedded firmware” style build**
- **Reproducible build workflow**
- Make targets + watch + run are an integrated dev loop.

- Actors: Developer, Emulator, (optional) Real SNES via EverDrive
- System: “Pangolin SNES ROM”
- External dependency: Emulator binaries
- Explicitly show artifacts (`.asm`, `.inc`, `.cfg`, `.bin`, `.cgram`, `.sfc`)
- Transformation steps (assemble, link, package, run)
- CPU, ROM, WRAM, PPU (VRAM/CGRAM), frame output

##### Concrete labeling guidance (use the repo names verbatim)

- `src/hello.asm` (Main ROM program)
- `src/hdr.inc` (Header / constants / macros)
- `src/snes.cfg` (SNES memory map)
- `assets/font.bin` (Font tiles)
- `assets/*4bpp.bin` (Graphics tiles)
- `assets/*.cgram` (Palette)
- `font.py` (Asset generator)
- `Makefile` (Build orchestration)
- `scripts/run_emulator.sh` (Emulator launcher)
- Output: `build/hello.sfc` + `hello.sfc`

- “Emulator (Mesen/Snes9x)”
- “SNES CPU (65c816)”
- “ROM (hello.sfc)”
- “WRAM”
- “PPU”
- “VRAM”
- “CGRAM”
- “Video Output (framebuffer/window)”

**Build-time lane:**
Developer/VSCode → Makefile → (Assembler) ← src/*.asm + hdr.inc → (Linker w/ snes.cfg/minimal.cfg + assets/*.bin/*.cgram) → build/hello.sfc → run_emulator.sh → Emulator

**Runtime lane:**
Emulator loads hello.sfc → CPU executes → writes VRAM/CGRAM → PPU renders → Video output

That separation captures the essential architecture of this repo while staying maximally faithful to what’s actually present.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% BUILD-TIME (Dev + Toolchain)
  %% =========================
  subgraph "Build-time (Developer workstation)"
    direction TB

    Dev["Developer (CLI / VS Code)"]:::actor

    subgraph "IDE Integration"
      direction TB
      VSCode["VS Code Tasks"]:::tool
      VSCodeDir[".vscode/"]:::tool
    end

    subgraph "Build Orchestration"
      direction TB
      Make["Makefile (build/run/watch/clean)"]:::tool
      Watch["scripts/watch.sh (watch + rebuild loop)"]:::tool
      Run["scripts/run_emulator.sh (emulator launcher)"]:::tool
      Readme["README.md (workflow/docs)"]:::doc
    end

    subgraph "Source (ROM program)"
      direction TB
      HelloAsm["src/hello.asm (main program)"]:::source
      TestAsm["src/test_minimal.asm (minimal ROM)"]:::source
      HdrInc["src/hdr.inc (header/macros/constants)"]:::source
      SnesCfg["src/snes.cfg (SNES memory map / ROM layout)"]:::config
      MinCfg["src/minimal.cfg (minimal memory map)"]:::config
    end

    subgraph "Assets (embedded data)"
      direction TB
      FontPy["font.py (asset generator)"]:::tool
      FontBin["assets/font.bin (font tiles)"]:::asset
      CupTiles["assets/cup_16x8_4bpp.bin (4bpp tiles)"]:::asset
      CupPal["assets/cup_16x8_palette.cgram (palette/CGRAM)"]:::asset
      AssetsNote["Note: assets are embedded in ROM;\nat runtime copied to VRAM/CGRAM"]:::note
    end

    subgraph "Toolchain (implicit)"
      direction TB
      Asm["Assembler"]:::toolchain
      Link["Linker / Packager\n(configured via *.cfg)"]:::toolchain
    end

    subgraph "Build Artifacts"
      direction TB
      OutBuild["build/hello.sfc (ROM image)"]:::output
      OutRoot["hello.sfc (copied to repo root)"]:::output
    end
  end

  %% =========================
  %% RUNTIME (Emulator/Console)
  %% =========================
  subgraph "Runtime (SNES execution model)"
    direction TB

    Emulator["Emulator (Mesen / Snes9x)\n(or real SNES + flashcart)"]:::external
    ROM["ROM (hello.sfc)"]:::rom
    CPU["SNES CPU (65c816)"]:::hw
    WRAM["WRAM"]:::mem
    PPU["PPU"]:::hw
    VRAM["VRAM"]:::mem
    CGRAM["CGRAM (palette)"]:::mem
    Video["Video Output (frame)"]:::external
  end

  %% =========================
  %% BUILD FLOW
  %% =========================
  Dev -->|"invokes_tasks"| VSCode
  VSCode -->|"configured_by"| VSCodeDir
  Dev -->|"runs_targets"| Make
  VSCode -->|"runs_targets"| Make

  Make -->|"watch"| Watch
  Watch -->|"triggers_rebuild"| Make

  FontPy -->|"generates/updates"| FontBin

  HelloAsm -->|"assembled_by"| Asm
  TestAsm -->|"assembled_by"| Asm
  HdrInc -.->|"included_by"| Asm

  Asm -->|"object_code"| Link
  SnesCfg -.->|"defines_layout/banks/vectors"| Link
  MinCfg -.->|"defines_layout(basic)"| Link

  FontBin -->|"embedded"| Link
  CupTiles -->|"embedded"| Link
  CupPal -->|"embedded"| Link

  Link -->|"produces"| OutBuild
  OutBuild -->|"copied_to_root"| OutRoot

  Make -->|"run"| Run
  Run -->|"launches_with"| Emulator
  Run -->|"uses"| OutRoot

  Readme -.->|"documents"| Make
  Readme -.->|"documents"| Run

  %% =========================
  %% RUNTIME FLOW
  %% =========================
  Emulator -->|"loads"| ROM
  ROM -->|"mapped_code+data"| CPU
  CPU <-->|"reads/writes"| WRAM
  CPU -->|"writes_regs+DMA"| PPU
  CPU -->|"loads_tiles"| VRAM
  CPU -->|"loads_palette"| CGRAM
  PPU -->|"reads"| VRAM
  PPU -->|"reads"| CGRAM
  PPU -->|"renders"| Video

  %% =========================
  %% Click Events (mapped components)
  %% =========================
  click HelloAsm "https://github.com/ojuliomiguel/snes_pangolin/blob/main/src/hello.asm"
  click TestAsm "https://github.com/ojuliomiguel/snes_pangolin/blob/main/src/test_minimal.asm"
  click HdrInc "https://github.com/ojuliomiguel/snes_pangolin/blob/main/src/hdr.inc"
  click SnesCfg "https://github.com/ojuliomiguel/snes_pangolin/blob/main/src/snes.cfg"
  click MinCfg "https://github.com/ojuliomiguel/snes_pangolin/blob/main/src/minimal.cfg"
  click FontBin "https://github.com/ojuliomiguel/snes_pangolin/blob/main/assets/font.bin"
  click CupTiles "https://github.com/ojuliomiguel/snes_pangolin/blob/main/assets/cup_16x8_4bpp.bin"
  click CupPal "https://github.com/ojuliomiguel/snes_pangolin/blob/main/assets/cup_16x8_palette.cgram"
  click FontPy "https://github.com/ojuliomiguel/snes_pangolin/blob/main/font.py"
  click Make "https://github.com/ojuliomiguel/snes_pangolin/tree/main/Makefile"
  click Run "https://github.com/ojuliomiguel/snes_pangolin/blob/main/scripts/run_emulator.sh"
  click Watch "https://github.com/ojuliomiguel/snes_pangolin/blob/main/scripts/watch.sh"
  click VSCodeDir "https://github.com/ojuliomiguel/snes_pangolin/tree/main/.vscode/"
  click Readme "https://github.com/ojuliomiguel/snes_pangolin/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#FFE8A3,stroke:#8A6D00,color:#1a1a1a,stroke-width:1px
  classDef tool fill:#CFE8FF,stroke:#1E5A8A,color:#0b2233,stroke-width:1px
  classDef toolchain fill:#BFE3FF,stroke:#0F4C75,color:#0b2233,stroke-width:1px
  classDef source fill:#D8F5D0,stroke:#2E7D32,color:#0b1f0b,stroke-width:1px
  classDef config fill:#E6D9FF,stroke:#5E35B1,color:#1b1036,stroke-width:1px
  classDef asset fill:#FFD6C9,stroke:#C04A2B,color:#2b120c,stroke-width:1px
  classDef output fill:#FFF1B8,stroke:#B08900,color:#2b2200,stroke-width:1px
  classDef rom fill:#FFE0B2,stroke:#E65100,color:#2b1400,stroke-width:1px
  classDef hw fill:#D7DCE2,stroke:#37474F,color:#101417,stroke-width:1px
  classDef mem fill:#E0F2F1,stroke:#00695C,color:#05312b,stroke-width:1px
  classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#1c0626,stroke-width:1px
  classDef note fill:#FFFFFF,stroke:#9E9E9E,color:#333333,stroke-dasharray: 4 3,stroke-width:1px
```
