# frost-phoenix/zig-sweeper architecture

> Architecture diagram of the GitHub repository frost-phoenix/zig-sweeper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frost-phoenix/zig-sweeper
- Repository: https://github.com/frost-phoenix/zig-sweeper

## Overview

##### Project Type and Purpose
- This is a single‐process, full‐stack (client‐only) graphical application.
- Purpose: Run a Minesweeper game on the desktop, parse CLI options, generate and manage the grid, handle input, and render graphics via Raylib.

##### File Structure
- Top‐level:
- build.zig / flake.nix / treefmt.nix → build & packaging
- res/ → resource assets (if any)
- src/ → core Zig modules
- src/ modules indicate a modular monolith:
- args.zig → CLI parsing
- common.zig → shared types & constants
- grid.zig → grid generation & cell‐state logic
- game.zig → game‐loop, win/loss, flag logic
- camera.zig → zoom/pan transforms
- camera.zig & main.zig → tie modules together
- main.zig → entrypoint, initializes Raylib, starts the loop

##### Key Components
a. External Systems
- Operating System (Windowing, input events)
- Raylib (graphics & input bindings)
b. Zig‐Sweeper Application Boundary
- Main Entrypoint (main.zig)
- Argument Parser (args.zig)
- Game Core
– Grid Manager (grid.zig)
– Game Logic (game.zig)
- Camera/Viewport (camera.zig)
- Renderer (calls Raylib API)
- Shared Utilities (common.zig)
c. Build & Packaging
- build.zig (Zig build script)
- flake.nix / nix-run (Nix integration)

##### Relationships & Data Flows
- On launch, Main invokes Argument Parser → config struct
- Main initializes Raylib window & input system
- Game Loop Iteration:
1. Poll OS events → feed into Input Handler
2. Input Handler modifies Game State (grid flags, cell opens)
3. Game Logic updates Grid Manager (win/loss, flood‐fill)
4. Camera updates viewport transforms
6. Raylib presents buffer to OS window
- The loop repeats until exit

##### Architectural Patterns & Principles
- Modular Monolith: clear separation by concern (parsing, logic, rendering)
- Single‐Threaded Game Loop: deterministic update→render cycle
- Dependency Injection: pass config & shared state into modules
- Layered: CLI → Core → Rendering → External

##### Elements
- Labels: “Argument Parser,” “Game Loop,” “Grid Manager,” etc.
- Optionally, annotate module filenames to map directly to code (e.g., args.zig)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-time Components
    subgraph "Build-time Components"
        direction TB
        BuildScript["build.zig"]:::build
        NixPackaging["flake.nix"]:::build
        BuildScript -->|builds| Binary["Zig-Sweeper Executable"]
        NixPackaging -->|packages| Binary
    end

    %% Runtime Components
    subgraph "Runtime Components"
        direction TB
        Binary --> Main["Main Entrypoint\n(src/main.zig)"]:::core
        Main --> ArgParser["Argument Parser\n(src/args.zig)"]:::core
        Main -->|initializes| RaylibLib["Raylib"]:::external
        Main -->|initializes| OS["Operating System"]:::external

        Main --> GameLoop["Game Loop"]:::core

        GameLoop -->|polls events| OS
        OS -->|events| GameLoop

        GameLoop --> InputHandler["Input Handler"]:::core
        InputHandler --> GameLogic["Game Logic\n(src/game.zig)"]:::core
        GameLogic --> GridManager["Grid Manager\n(src/grid.zig)"]:::core
        GridManager --> GameLogic

        GameLoop --> Camera["Camera/Viewport\n(src/camera.zig)"]:::core
        GameLoop --> Renderer["Renderer\n(draw calls via Raylib)"]:::core

        Renderer --> RaylibLib
        RaylibLib --> OS
    end

    %% Shared Utilities and Resources
    SharedUtils["Shared Utilities\n(src/common.zig)"]:::core
    Binary --> SharedUtils
    Renderer --> Resources["Resource Assets\n(res/)"]:::external

    %% Click Events
    click Main "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/main.zig"
    click ArgParser "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/args.zig"
    click GridManager "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/grid.zig"
    click GameLogic "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/game.zig"
    click Camera "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/camera.zig"
    click SharedUtils "https://github.com/frost-phoenix/zig-sweeper/blob/main/src/common.zig"
    click BuildScript "https://github.com/frost-phoenix/zig-sweeper/blob/main/build.zig"
    click NixPackaging "https://github.com/frost-phoenix/zig-sweeper/blob/main/flake.nix"
    click Resources "https://github.com/frost-phoenix/zig-sweeper/tree/main/res/"

    %% Styles
    classDef core fill:#b3d1ff,stroke:#333,stroke-width:1px
    classDef external fill:#b3ffb3,stroke:#333,stroke-width:1px
    classDef build fill:#d9d9d9,stroke:#333,stroke-width:1px
```
