# cieria/rusty-tetris architecture

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

- Interactive diagram: https://gitdiagram.com/cieria/rusty-tetris
- Repository: https://github.com/cieria/rusty-tetris

## Overview

##### Project Type and Purpose
- This is a Rust-based standalone game application (a Tetris clone) that uses SDL2 for rendering and input.
- It’s organized as a Cargo workspace of multiple crates (libraries) plus one binary crate (`tetris`).

##### Key Components
A. Core Math & Data Structures
- `vecmath` crate: 2D coordinate and rotation utilities.
- `matrix` crate: grid/matrix operations (collision, line clears, etc.).
B. Game Logic & Engine
- `game` crate: overall game state, rules, scoring, soft/hard drop mechanics.
- `engine` crate: defines a public interface to drive the game loop (frame timing, step/update).
C. Application Layer (Binary)
- `tetris` crate: the executable that ties everything together.
– Initializes SDL2 & SDL2_ttf
– Handles input (keyboard events)
– Invokes `engine` to update `game` state each frame
– Calls into `matrix` & `pieces` via `game`
– Renders current game state to the screen
D. External Services & Libraries
- SDL2 (graphics + input)
- SDL2_ttf (text rendering)
- `rand` crate (random piece generation)

##### Interactions and Data Flow
- At startup, `tetris` initializes external libraries (SDL2, SDL2_ttf).
- The main loop in `tetris` invokes the `engine` interface each tick:
→ Engine calls into `game` crate to advance game state.
→ `game` uses `pieces` (to spawn/rotate tetrominoes), `matrix` (to test collisions, clear lines), and `vecmath` (for coordinate math).
→ `game` returns updated state (grid contents, active piece, score).
- Back in `tetris`, the updated state is rendered via SDL2 calls.
- Keyboard events captured by SDL2 are mapped to `game` actions (move left/right, rotate, drop).

##### Architectural Patterns & Design Principles
- Layered architecture: low-level math → domain logic → engine interface → application UI/IO.
- Separation of concerns:
- Crates at the bottom only compute geometry/matrices.
- Game rules separated in `game`.
- I/O and rendering isolated in `tetris`.
- Dependency inversion in `engine`: the binary drives the engine, not the other way around.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Math Layer
    subgraph "Math Layer"
        vecmath["vecmath"]:::math
        matrix["matrix"]:::math
        pieces["pieces"]:::math
    end

    %% Logic Layer
    subgraph "Logic Layer"
        game["game"]:::logic
        engine["engine"]:::logic
    end

    %% Application Layer
    subgraph "Application Layer"
        tetris["tetris"]:::app
    end

    %% External Dependencies
    SDL2["SDL2"]:::external
    SDL2_ttf["SDL2_ttf"]:::external
    rand["rand"]:::external

    %% Dependencies
    matrix -->|"uses vecmath"| vecmath
    pieces -->|"uses vecmath"| vecmath
    game -->|"uses matrix"| matrix
    game -->|"uses pieces"| pieces
    engine -->|"calls game"| game
    tetris -->|"calls engine"| engine
    game -->|"random piece gen"| rand

    %% Runtime Data Flow
    SDL2 -.->|"input & render API"| tetris
    tetris -->|"draw calls"| SDL2
    SDL2_ttf -.->|"text render"| tetris

    %% Click Events
    click vecmath "https://github.com/cieria/rusty-tetris/tree/main/vecmath/"
    click matrix "https://github.com/cieria/rusty-tetris/tree/main/matrix/"
    click pieces "https://github.com/cieria/rusty-tetris/tree/main/pieces/"
    click game "https://github.com/cieria/rusty-tetris/tree/main/game/"
    click engine "https://github.com/cieria/rusty-tetris/tree/main/engine/"
    click tetris "https://github.com/cieria/rusty-tetris/blob/main/tetris/src/main.rs"

    %% Styles
    classDef math fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px
    classDef logic fill:#D5F5E3,stroke:#196F3D,stroke-width:2px
    classDef app fill:#FAD7A0,stroke:#B9770E,stroke-width:2px
    classDef external fill:#F2F3F4,stroke:#7F8C8D,stroke-width:2px,stroke-dasharray: 5 5
```
