# chunghha/tui_sudoku architecture

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

- Interactive diagram: https://gitdiagram.com/chunghha/tui_sudoku
- Repository: https://github.com/chunghha/tui_sudoku

## Overview

##### Project Type & Purpose
- The project is a terminal-based Sudoku game written in Rust.
- It uses the ratatui and crossterm libraries to build a text user interface (TUI) and handles game logic such as difficulty settings, input processing, puzzle generation, and win detection.

##### File Structure
- Top-Level Files/Folders:
- .github: Contains CI/CD configuration (e.g., GitHub Actions workflows in release.yml) for automated releases or checks.
- Cargo.toml and Cargo.lock: Define Rust dependencies and project metadata.
- Taskfile.yml: Likely used for alternative build/tasks automation.
- screenshots: Provides visual examples (e.g., win detection screen).
- The src Directory:
- main.rs: The entry point where the application initialization and startup occur.
- app.rs: Likely manages the central application logic and ties together different components.
- sudoku.rs: Handles the Sudoku puzzle’s logic, generation, and validation.
- ui.rs: Contains functions and modules for rendering the UI, handling user interactions, and managing input events.

##### Insights from the README
- The README outlines the project’s gameplay features (difficulty levels, a clean terminal UI with keyboard and mouse inputs, validation, and solution toggling).
- Dependencies:
- ratatui and crossterm for drawing/rendering the terminal UI.
- rand for puzzle generation/shuffling.
- Controls and game flow are clearly defined, which suggests a modular design separating user input, game logic, and rendering.

a. Main Components:
- Entry Point (main.rs): Application startup.
- Application Controller (app.rs): Centralizes flow control, business logic, and state management.
- Sudoku Engine (sudoku.rs): Contains the logic for puzzle generation, difficulty settings, move validation, and win detection.
- User Interface Module (ui.rs): Responsible for rendering the terminal display using ratatui and handling input events via crossterm.
- CI/CD Pipeline (.github/workflows): Manages automated builds and releases (can be shown as an external process or supporting service).

b. Relationships and Interactions:
- The main entry point calls the application controller to initialize and start the game.
- The app module coordinates the game’s state, invoking:
– The Sudoku engine for setting up and maintaining the puzzle.
– The UI module to render the interface and process events.
- The UI module sends user interactions (via keyboard or mouse) back to the app logic, which then interacts with the sudoku engine.
- The CI/CD pipeline (GitHub Actions) ensures compatibility and quality through automated testing and releases.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Code is clearly divided into modules handling distinct responsibilities (input/rendering vs puzzle logic).
- Modular Design: Each Rust file (app, sudoku, ui) encapsulates a specific aspect of the game.
- Dependency Management: Use of external crates to manage specialized functionality (TUI and randomness).

d. Technologies and Key Libraries:
- Rust as the primary programming language.
- ratatui and crossterm for rendering the terminal UI.
- rand crate for generating randomized puzzle values.
- Cargo for building and dependency management.
- GitHub Actions for CI/CD integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules Subgraph
    subgraph "Core Modules"
        A["Main (main.rs)"]:::core
        B["Application Controller (app.rs)"]:::core
        C["Sudoku Engine (sudoku.rs)"]:::logic
        D["User Interface (ui.rs)"]:::ui
    end

    %% External Support Nodes
    E["CI/CD Pipeline (.github/workflows)"]:::ci
    F["External Libraries (ratatui, crossterm, rand)"]:::external

    %% Relationships
    A -->|"calls"| B
    B -->|"initializes"| C
    B -->|"initializes"| D
    D -->|"sendsInputTo"| B
    B -.->|"uses"| F
    F -.->|"monitoredBy"| E

    %% Click Events
    click A "https://github.com/chunghha/tui_sudoku/blob/main/src/main.rs"
    click B "https://github.com/chunghha/tui_sudoku/blob/main/src/app.rs"
    click C "https://github.com/chunghha/tui_sudoku/blob/main/src/sudoku.rs"
    click D "https://github.com/chunghha/tui_sudoku/blob/main/src/ui.rs"
    click E "https://github.com/chunghha/tui_sudoku/blob/main/.github/workflows/release.yml"

    %% Styling
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef logic fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef ui fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef ci fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
