# techinqproj-2025-s1/2025s1_tip_c08_team3 architecture

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

- Interactive diagram: https://gitdiagram.com/techinqproj-2025-s1/2025s1_tip_c08_team3
- Repository: https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3

## Overview

##### Project type and purpose
- This is a Python-based desktop “game launcher” application that bundles several mini-games (MathFlip, TetrisMath, Sequence Game, Spell Quest, Typing Game, Word Pop).
- The `launcher` module provides a unified UI, settings, and high-score management. Each game is a self-contained submodule under `games/`.

##### File structure
- Top-level packages and files:
- `launcher/` – core application (UI, menus, button widgets, settings, score management)
- `games/` – one subdirectory per game, each with its own game logic, UI, constants, and persistence files (high-score JSON or text)
- `config.json` – global configuration for the launcher or games
- `scores/` – aggregate score storage (e.g., `tetris_math_scores.json`)
- `launcher.py` – entry point that bootstraps the launcher UI
- `tests/` + `pytest.ini` – end-to-end and unit tests for launcher and games
- GitHub Actions workflows under `.github/workflows` – CI for linting and tests
- Notice each game submodule follows a similar MVC-like breakdown: constants, UI code, game logic, persistence (highscores/leaderboards).

##### README for additional insights
- The README itself is focused on GitHub rules and CI, but it confirms that PyLint is integrated and that branches/pr workflows are used to enforce quality checks.

a. Main components:
- User Interface Layer (Launcher UI, Menus, Buttons)
- Game Modules (MathFlip, TetrisMath, etc.)
- Configuration Manager (reads `config.json`)
- Persistence Layer (reads/writes JSON/text files in `games/*` and `scores/`)
- Test Harness (pytest suite)
- CI Pipeline (GitHub Actions → Linting & Tests)
b. Relationships & interactions:
- User → clicks on Launcher UI → invokes Game Module
- Each Game Module → communicates with Persistence Layer to load/save highscores/leaderboards
- Launcher & Games → read global or per-game config from Configuration Manager
- Tests → import and exercise Launcher and Game modules (unit/integration)
- CI Pipeline → runs lint and pytest on commits/PRs
c. Architectural patterns & principles:
- Modular design: each game is an independent package plugged into a common launcher framework
- MVC-like separation within each game (constants/model, UI/view, game logic/controller)
- Single entry point (`launcher.py`) for the application
- Externalized configuration and persistence to JSON/text files
- Automated pipelines enforcing code quality
d. Key technologies & libraries:
- Python 3.x, pytest, PyLint
- Standard library for JSON, file I/O, and possibly a GUI library (e.g., pygame or tkinter if used indirectly in `ui.py`)

##### Elements
- From User → Launcher UI → Game Module
- From Launcher/Game → Configuration Manager (read)
- From Launcher/Game → Persistence Layer (read/write)
- From CI Pipeline → triggers Lint & Tests → Test Suite
- Game logic modules in another

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% Launcher UI Layer
    subgraph "Launcher UI Layer"
        LauncherEntry["launcher.py"]:::ui
        Menus["menus.py"]:::ui
        Button["button.py"]:::ui
        SettingsMenu["settings_menu.py"]:::ui
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        GlobalConfig["config.json"]:::config
        LauncherConstants["constants.py"]:::config
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        SharedScores["tetris_math_scores.json"]:::data
        MFHighscoreLogic["highscore.py"]:::data
        MFHighscoreData["highscore.json"]:::data
        SQLeaderboard["leaderboard.json"]:::data
        TGLeaderboard["leaderboard.json"]:::data
        WPHighscore["highscore.txt"]:::data
    end

    %% Game Modules
    subgraph "Game Modules"
        subgraph "MathFlip" 
            MFConsts["constants.py"]:::game
            MFLogic["mathflip_game.py"]:::game
            MFQuestion["question.py"]:::game
            MFEvents["events.py"]:::game
            MFUI["ui.py"]:::game
            MFFonts["fonts.py"]:::game
        end
        subgraph "TetrisMath"
            TMMain["main.py"]:::game
            TMCore["tetris.py"]:::game
            TMTetromino["tetromino.py"]:::game
            TMMathChallenge["math_challenge.py"]:::game
            TMUI["ui.py"]:::game
            TMNet["network.py"]:::game
        end
        subgraph "Sequence Game"
            SeqAll["sequence.py"]:::game
        end
        subgraph "Spell Quest"
            SQLogic["spell_quest.py"]:::game
        end
        subgraph "Typing Game"
            TGLogic["typing_game.py"]:::game
        end
        subgraph "Word Pop"
            WPLogic["python_balloon_pop.py"]:::game
            WPWords["words.txt"]:::data
        end
    end

    %% Test Harness
    subgraph "Test Suite"
        TestsDir["tests/"]:::tests
        PyTestConfig["pytest.ini"]:::tests
        TestLaunch["test_launcher.py"]:::tests
        TestMF["test_math_flip.py"]:::tests
        TestNet["test_network.py"]:::tests
        TestScore["test_score.py"]:::tests
        TestTetris["test_tetris_math.py"]:::tests
    end

    %% CI Pipeline
    subgraph "CI Pipeline"
        Workflow["python-app.yml"]:::ci
        LintReq["lint-requirements.txt"]:::ci
    end

    %% Connections
    User -->|selects game| LauncherEntry
    LauncherEntry --> Menus
    LauncherEntry --> Button
    LauncherEntry --> SettingsMenu

    LauncherEntry -->|load config| GlobalConfig
    LauncherEntry -->|load constants| LauncherConstants

    Menus -->|launch game| MFLogic
    Menus -->|launch game| TMMain
    Menus -->|launch game| SeqAll
    Menus -->|launch game| SQLogic
    Menus -->|launch game| TGLogic
    Menus -->|launch game| WPLogic

    subgraph ConfigFlow
        LauncherEntry -->|read| GlobalConfig
        MFLogic -->|read| GlobalConfig
        TMMain -->|read| GlobalConfig
    end

    subgraph PersistenceFlow
        MFHighscoreLogic -->|write/read| SharedScores
        MFLogic -->|invoke| MFHighscoreLogic
        SQLogic -->|write/read| SQLeaderboard
        TGLogic -->|write/read| TGLeaderboard
        WPLogic -->|write/read| WPHighscore
        TMMain -->|no local highscore| SharedScores
    end

    %% Test and CI
    Workflow -->|runs| TestsDir
    Workflow -->|uses| PyTestConfig
    TestsDir -->|tests| LauncherEntry
    TestsDir -->|tests| MFLogic
    TestsDir -->|tests| TMMain

    %% Click Events
    click LauncherEntry "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/launcher.py"
    click Menus "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/launcher/menus.py"
    click Button "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/launcher/button.py"
    click SettingsMenu "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/launcher/settings_menu.py"
    click GlobalConfig "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/config.json"
    click LauncherConstants "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/launcher/constants.py"
    click SharedScores "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/scores/tetris_math_scores.json"
    click MFHighscoreLogic "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/highscore.py"
    click MFHighscoreData "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/highscore.json"
    click SQLeaderboard "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/spell_quest/leaderboard.json"
    click TGLeaderboard "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/typing_game/leaderboard.json"
    click WPHighscore "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/word_pop/highscore.txt"
    click MFConsts "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/constants.py"
    click MFLogic "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/mathflip_game.py"
    click MFQuestion "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/question.py"
    click MFEvents "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/events.py"
    click MFUI "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/ui.py"
    click MFFonts "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/MathFlip/fonts.py"
    click TMMain "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/main.py"
    click TMCore "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/tetris.py"
    click TMTetromino "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/tetromino.py"
    click TMMathChallenge "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/math_challenge.py"
    click TMUI "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/ui.py"
    click TMNet "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/TetrisMath/network.py"
    click SeqAll "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/sequence_game/sequence.py"
    click SQLogic "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/spell_quest/spell_quest.py"
    click TGLogic "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/typing_game/typing_game.py"
    click WPLogic "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/word_pop/python_balloon_pop.py"
    click WPWords "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/games/word_pop/words.txt"
    click TestsDir "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/tree/main/tests/"
    click PyTestConfig "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/pytest.ini"
    click TestLaunch "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/tests/test_launcher.py"
    click TestMF "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/tests/test_math_flip.py"
    click TestNet "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/tests/test_network.py"
    click TestScore "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/tests/test_score.py"
    click TestTetris "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/tests/test_tetris_math.py"
    click Workflow "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/.github/workflows/python-app.yml"
    click LintReq "https://github.com/techinqproj-2025-s1/2025s1_tip_c08_team3/blob/main/.github/workflows/lint-requirements.txt"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#3498DB
    classDef game fill:#D5F5E3,stroke:#27AE60
    classDef data fill:#FCF3CF,stroke:#F1C40F,stroke-dasharray: 5 5
    classDef config fill:#FCF3CF,stroke:#F39C12
    classDef tests fill:#FADBD8,stroke:#E74C3C
    classDef ci fill:#E8E8E8,stroke:#95A5A6
    classDef external fill:#F2F3F4,stroke:#7F8C8D,stroke-dasharray: 2 2
```
