# gasinfinity/zitrus architecture

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

- Interactive diagram: https://gitdiagram.com/gasinfinity/zitrus
- Repository: https://github.com/gasinfinity/zitrus

## Overview

##### Project type and purpose
- This is Zitrus, a 3DS homebrew SDK written entirely in Zig. It provides:
- A core library (modules for Horizon OS, PICA200‐style graphics “Mango,” hardware definitions, compression, formatting, memory management)
- A suite of command‐line tools (assemblers, packers, format inspectors)
- Example/demo applications (bitmap, flappy bird, GPU playground, info, panic, mango/hello_triangle, etc.)
- Build scripts and CI/CD for packaging libraries and demos into .elf/.3dsx

##### File structure
Top‐level directories:
- src – the core SDK modules:
– horizon/… (OS services, IPC, memory, panic, heap)
– hardware/… (register definitions, drivers: csnd, hid, pica, etc.)
– mango/… (Vulkan‐style graphics API wrappers)
– compress, fmt, math, memory, c (bindings), zitrus.zig root
- tools – host‐side CLI tools: 3dsx, RomFs, ExeFs, Smdh, Pica assembler/disassembler, Firm/Ncch, LZrev compressor
- demo – sample apps built on Zitrus (each with its own build.zig and sources)
- scripts – helpers (e.g., generate SPIR-V spec)
- test – unit/integration tests for Horizon and Mango modules
- build.zig, flake.nix/flake.lock – project‐wide build definition & Nix support
- docs – markdown docs and images for PICA shader formats, etc.

Architectural patterns:
- Layered library architecture:
– Lowest layer: hardware register definitions
– Next: Horizon OS bindings & services
– Next: Mango graphics abstraction over PICA200
– Cross‐cutting modules: compress, fmt, memory, math
- “Tools” are independent Zig executables that consume core modules to manipulate homebrew formats
- “Demo” apps are Zig executables that import the Zitrus library and use its modules to build .elf → .3dsx packages

##### README for insights
- Targets ARM11/horizon on real 3DS hardware or emulator
- Uses Zig’s build system (build.zig + dependency API) to wire up modules and linker scripts
- Provides MakeSmdh, Make3dsx, MakeRomFs helpers for final packaging
- Demonstrates high‐level usage: import zitrus, create Executable, set linker script, embed assets, produce .3dsx

##### Elements
- Clear labels: “Demo Apps,” “Zitrus Core,” “Tools,” “Build System,” “3DS Runtime,” “Hardware”
– Demo → Core (import/depends)
– Core → Horizon OS services (API calls)
– Core → Hardware modules → actual registers
– Build System → CLI Tools → final artifact
– 3DS Launcher → .3dsx → runtime flow
– Orange for Tools (CLI executables)
– Gray for Build System elements (build.zig, flake)
– Red for 3DS Runtime & Hardware blocks
- Annotations for key data flows (compilation, packaging, runtime calls, GPU submission)

##### Final advice
- Break the system into as many meaningful components as needed, but group related modules into logical clusters (e.g., “Horizon Services,” “Mango Graphics,” “Hardware Drivers”).
- Both the compile‐time dependency graph (demo → core → horizon/hardware) and the run‐time call flows (application → Horizon services → hardware).
- Be detailed in labeling module names, build steps, and format conversions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Zone
    subgraph "Developer Zone" 
        direction TB
        Demo_Bitmap["Bitmap App"]:::demo
        Demo_Flappy["Flappy Bird App"]:::demo
        Demo_GPU["GPU Playground App"]:::demo
        Demo_Info["Info App"]:::demo
        Demo_Panic["Panic App"]:::demo
        Demo_Hello["Mango Hello Triangle App"]:::demo
        Demo_LibApplets["LibApplets App"]:::demo
    end

    %% Zitrus Core Library
    subgraph "Zitrus Core Library" 
        direction TB
        Core_Root["zitrus.zig (Manifest)"]:::core
        subgraph "Modules"
            direction TB
            Core_Hardware["Hardware Module"]:::core
            Core_Horizon["Horizon Module"]:::core
            Core_Mango["Mango Module"]:::core
            Core_Compress["Compress Module"]:::core
            Core_Fmt["Formatting Module"]:::core
            Core_Math["Math Module"]:::core
            Core_Memory["Memory Management Module"]:::core
            Core_C["C Bindings Module"]:::core
        end
    end

    %% Tools Layer
    subgraph "Tools Layer" 
        direction TB
        Tools_CLIs["CLI Executables"]:::tools
    end

    %% Build System
    subgraph "Build System" 
        direction TB
        Build_Script["build.zig"]:::build
        Packaging["Packaging Helpers"]:::build
        Linker["Linker Scripts"]:::build
        CI["CI/CD Workflows"]:::build
        Nix["Nix Support"]:::build
    end

    %% 3DS Runtime & Hardware
    subgraph "3DS Runtime & Hardware"
        direction TB
        Launcher["Homebrew Launcher"]:::runtime
        Xenelf[".3dsx Runtime"]:::runtime
        Runtime_Horizon["Horizon OS Services"]:::runtime
        Runtime_Mango["Mango GPU Runtime"]:::runtime
        HW_PICA["PICA200 GPU"]:::runtime
        HW_DSP["DSP"]:::runtime
        HW_CSND["CSND"]:::runtime
    end

    %% Dependencies & Flows
    Demo_Bitmap -->|"imports"| Core_Root
    Demo_Flappy -->|"imports"| Core_Root
    Demo_GPU -->|"imports"| Core_Root
    Demo_Info -->|"imports"| Core_Root
    Demo_Panic -->|"imports"| Core_Root
    Demo_Hello -->|"imports"| Core_Root
    Demo_LibApplets -->|"imports"| Core_Root

    Core_Root -->|"depends on"| Core_C
    Core_Root --> Core_Hardware
    Core_Root --> Core_Horizon
    Core_Root --> Core_Mango
    Core_Root --> Core_Compress
    Core_Root --> Core_Fmt
    Core_Root --> Core_Math
    Core_Root --> Core_Memory

    Core_Hardware -->|"register defs"| Runtime_Horizon
    Core_Horizon -->|"OS bindings"| Runtime_Horizon
    Core_Mango -->|"graphics API"| Runtime_Mango

    Tools_CLIs -->|"uses"| Core_Compress
    Tools_CLIs --> Core_Fmt
    Tools_CLIs --> Core_C
    Tools_CLIs --> Core_Mango

    Build_Script -->|"compiles"| Core_Root
    Build_Script --> Demo_Bitmap
    Build_Script --> Demo_Flappy
    Build_Script --> Demo_GPU
    Build_Script --> Demo_Info
    Build_Script --> Demo_Panic
    Build_Script --> Demo_Hello
    Build_Script --> Demo_LibApplets

    Packaging -->|"packages .elf to .3dsx"| Tools_CLIs
    Packaging --> Linker

    Build_Script --> Packaging
    Build_Script --> Linker
    Build_Script --> CI
    Build_Script --> Nix

    Launcher -->|"loads"| Xenelf
    Xenelf --> Runtime_Horizon
    Runtime_Horizon --> Runtime_Mango
    Runtime_Mango --> HW_PICA
    Runtime_Horizon --> HW_DSP
    Runtime_Horizon --> HW_CSND

    %% Click Events
    click Demo_Bitmap "https://github.com/gasinfinity/zitrus/tree/main/demo/bitmap/"
    click Demo_Flappy "https://github.com/gasinfinity/zitrus/tree/main/demo/flappy/"
    click Demo_GPU "https://github.com/gasinfinity/zitrus/tree/main/demo/gpu/"
    click Demo_Info "https://github.com/gasinfinity/zitrus/tree/main/demo/info/"
    click Demo_Panic "https://github.com/gasinfinity/zitrus/tree/main/demo/panic/"
    click Demo_Hello "https://github.com/gasinfinity/zitrus/tree/main/demo/mango/hello_triangle/"
    click Demo_LibApplets "https://github.com/gasinfinity/zitrus/tree/main/demo/libapplets/"
    click Core_Root "https://github.com/gasinfinity/zitrus/blob/main/src/zitrus.zig"
    click Core_Horizon "https://github.com/gasinfinity/zitrus/blob/main/src/horizon.zig"
    click Core_Hardware "https://github.com/gasinfinity/zitrus/blob/main/src/hardware.zig"
    click Core_Mango "https://github.com/gasinfinity/zitrus/blob/main/src/mango.zig"
    click Core_Compress "https://github.com/gasinfinity/zitrus/blob/main/src/compress.zig"
    click Core_Fmt "https://github.com/gasinfinity/zitrus/blob/main/src/fmt.zig"
    click Core_Math "https://github.com/gasinfinity/zitrus/blob/main/src/math.zig"
    click Core_Memory "https://github.com/gasinfinity/zitrus/blob/main/src/memory.zig"
    click Core_C "https://github.com/gasinfinity/zitrus/blob/main/src/c.zig"
    click Tools_CLIs "https://github.com/gasinfinity/zitrus/tree/main/tools/"
    click Build_Script "https://github.com/gasinfinity/zitrus/blob/main/build.zig"
    click Packaging "https://github.com/gasinfinity/zitrus/blob/main/build/Make3dsx.zig"
    click Packaging "https://github.com/gasinfinity/zitrus/blob/main/build/MakeRomFs.zig"
    click Packaging "https://github.com/gasinfinity/zitrus/blob/main/build/MakeSmdh.zig"
    click Packaging "https://github.com/gasinfinity/zitrus/blob/main/build/AssembleZpsm.zig"
    click Linker "https://github.com/gasinfinity/zitrus/blob/main/build/ld/arm-3ds.ld"
    click CI "https://github.com/gasinfinity/zitrus/blob/main/.github/workflows/ci.yaml"
    click CI "https://github.com/gasinfinity/zitrus/blob/main/.github/workflows/cd.yaml"
    click CI "https://github.com/gasinfinity/zitrus/blob/main/.github/workflows/release-tag.yaml"
    click Nix "https://github.com/gasinfinity/zitrus/blob/main/flake.nix"
    click Nix "https://github.com/gasinfinity/zitrus/blob/main/flake.lock"

    %% Styles
    classDef demo fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef tools fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef build fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef runtime fill:#ffcccc,stroke:#333,stroke-width:1px
```
