# frost-phoenix/2048-cli architecture

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

- Interactive diagram: https://gitdiagram.com/frost-phoenix/2048-cli
- Repository: https://github.com/frost-phoenix/2048-cli

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **single-binary terminal application**: a **2048 game implemented in C for GNU/Linux**. There’s no client/server split, no network, and no persistent DB. The “system” is primarily:
- A **CLI process** running in a terminal
- Interacting with the **user via keyboard input**
- Rendering to the **terminal display**
- Maintaining **in-memory game state** (board, score, undo)
- Built/installed via **Makefile** into `/usr/local/bin` (or configured path)

From the tree:

- `src/main.c`

- `src/board.c` + `include/board.h`
**Core game logic / domain layer**: board representation, move/merge rules, random tile spawn, score updates, game-over checks, undo snapshot storage.

- `include/common.h`
Shared types/constants/utilities across modules (directions enum, board size constants, helper macros).

- `Makefile`
**Build + packaging**: compile/link steps, output location (`./bin/2048` per README), `make run`, `make install/uninstall`.

- `.github/assets/*`
Documentation assets only (not runtime).

This is essentially a **layered, single-process C program** with a clean split between **game logic** and **rendering**, orchestrated by `main`.

##### What the README adds (runtime behavior to show)
- **Score tracking** → stored in game state, updated during merges
- **Undo one move** → requires a “previous state” snapshot (board + score) and a trigger key
- **After each valid move** → spawn new tile (2/4) in empty spot
- **End condition** → no moves possible / board full

“environment dependencies”:
- Runs in **terminal on GNU/Linux**
- Built with **GCC/Clang + GNU Make**

- Header dependencies and call directions

- Loop: read input → update board → update score → render → check end
- Undo path and “invalid move” path (no spawn, maybe no redraw or still redraw)

These two together capture “what it is” and “how it runs.”

##### Runtime “system” components (high-level)
- **User**
- **Terminal / TTY (stdin/stdout)**
- **2048 Process (single binary)** containing:
- Input handling (likely in `main.c`)
- Game logic (`board.c`)
- Shared definitions (`common.h`)

##### Code modules (lower-level)
- `main.c` (Controller / Orchestrator)
- calls → `board` functions (apply move, spawn, check end, undo)
- reads ← keyboard input from terminal

- `board.c` (Domain)
- owns → `GameState` (board grid, score, undo snapshot)
- uses → `common.h` constants/types
- returns → “move result” (changed? score delta? game over?)

- takes → `GameState` or board+score as input
- writes → terminal output (stdout)
- may use → terminal control sequences (clear screen, cursor moves)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% Diagram 1: Static component/module architecture
%% =======================
subgraph D1["Static Component / Module Diagram (Code Architecture)"]
direction TB

    subgraph EXT1["Environment (GNU/Linux Terminal)"]
    direction TB
        User["User"]:::actor
        TTY["Terminal / TTY"]:::external
        STDIN["stdin (arrowkeys/undo/quit)"]:::external
        STDOUT["stdout (ANSI/printing)"]:::external
        User -->|"keypress"| TTY
        TTY -->|"provides"| STDIN
        STDOUT -->|"visualfeedback"| TTY
        TTY -->|"display"| User
    end

    subgraph P1["2048 CLI (single process / single binary)"]
    direction TB

        Main["Game Loop / Controller (main.c)"]:::orchestrator

        subgraph MODS1["Internal Modules"]
        direction TB
            Board["Game State + Rules (board.c)"]:::domain
            Draw["Terminal Renderer (draw.c)"]:::presentation
            Common["Shared Types / Constants (common.h)"]:::shared
            RNG(("RNG (tile spawn)")):::utility
        end

        BoardH["Board Public API (board.h)"]:::api
        DrawH["Draw Public API (draw.h)"]:::api
    end

    %% I/O relationships
    STDIN -->|"readinput"| Main
    Draw -.->|"writes"| STDOUT

    %% Module dependencies / calls
    Main -->|"calls"| BoardH
    Main -->|"calls"| DrawH
    BoardH -->|"implementedby"| Board
    DrawH -->|"implementedby"| Draw

    Board -->|"uses"| Common
    Draw -->|"uses"| Common
    Board <-->|"randomtile"| RNG

    %% Data (dashed) - Draw reads state to render
    Board -.->|"GameState(board+score+undo)"| Draw
end

%% =======================
%% Diagram 2: Runtime control/data flow (game loop)
%% =======================
subgraph D2["Runtime Control Flow Diagram (Game Loop)"]
direction TB

    Start(["Process start"]):::startstop
    Loop{{"Main Loop"}}:::loop
    ReadKey["Read key from stdin"]:::orchestrator
    Decode["Decode input to action (Move/Undo/Quit)"]:::orchestrator

    ApplyMove["ApplyMove(direction)"]:::domain
    MoveChanged{"Move changed board?"}:::decision
    Spawn["SpawnTile(2/4 in empty spot)"]:::domain
    UpdateScore["Update score (merge deltas)"]:::domain

    Undo["Undo: Restore previous snapshot"]:::domain

    Render["Render board + score (ANSI)"]:::presentation
    CheckEnd{"Game over / no moves?"}:::decision
    End(["Exit"]):::startstop

    Start --> Loop
    Loop --> ReadKey --> Decode

    Decode -->|"Move"| ApplyMove --> MoveChanged
    MoveChanged -->|"Yes"| Spawn --> UpdateScore --> Render
    MoveChanged -->|"No"| Render

    Decode -->|"Undo"| Undo --> Render
    Decode -->|"Quit"| End

    Render --> CheckEnd
    CheckEnd -->|"No"| Loop
    CheckEnd -->|"Yes"| End
end

%% =======================
%% Build / Install lifecycle
%% =======================
subgraph D3["Build & Install (Lifecycle)"]
direction TB
    Dev["Developer"]:::actor
    Make["Build + Install System (Makefile)"]:::build
    Bin["Output: bin/2048"]:::artifact
    Install["Install target (/usr/local/bin/2048)"]:::artifact
    Docs["Project Docs (README)"]:::docs
    Assets["Docs Assets (.github/assets)"]:::docs

    Dev -->|"make"| Make -->|"builds"| Bin
    Dev -->|"sudo make install"| Make -->|"copies"| Install
    Docs -.->|"documentscontrols/build"| Make
    Assets -.->|"screenshots/media"| Docs
end

%% =======================
%% Click events (component mapping)
%% =======================
click Main "https://github.com/frost-phoenix/2048-cli/blob/main/src/main.c"
click Board "https://github.com/frost-phoenix/2048-cli/blob/main/src/board.c"
click BoardH "https://github.com/frost-phoenix/2048-cli/blob/main/include/board.h"
click Draw "https://github.com/frost-phoenix/2048-cli/blob/main/src/draw.c"
click DrawH "https://github.com/frost-phoenix/2048-cli/blob/main/include/draw.h"
click Common "https://github.com/frost-phoenix/2048-cli/blob/main/include/common.h"
click Make "https://github.com/frost-phoenix/2048-cli/tree/main/Makefile"
click Docs "https://github.com/frost-phoenix/2048-cli/blob/main/README.md"
click Assets "https://github.com/frost-phoenix/2048-cli/tree/main/.github/assets/"

%% =======================
%% Styles
%% =======================
classDef actor fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#1B1B1B;
classDef external fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0B1B2B;
classDef orchestrator fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#2B1600;
classDef domain fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#0C1F0E;
classDef presentation fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#2A2200;
classDef shared fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#111;
classDef api fill:#E0F7FA,stroke:#00838F,stroke-width:1px,color:#002022;
classDef utility fill:#F1F8E9,stroke:#558B2F,stroke-width:1px,color:#12210A;
classDef build fill:#FCE4EC,stroke:#C2185B,stroke-width:1px,color:#2A0012;
classDef docs fill:#E8EAF6,stroke:#283593,stroke-width:1px,color:#0A0B20;
classDef artifact fill:#F5F5F5,stroke:#616161,stroke-width:1px,color:#111;

classDef decision fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#2A0505;
classDef loop fill:#E1F5FE,stroke:#0277BD,stroke-width:1px,color:#06202D;
classDef startstop fill:#E0F2F1,stroke:#00695C,stroke-width:1px,color:#03211D;
```
