# femitun/pict-o-word architecture

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

- Interactive diagram: https://gitdiagram.com/femitun/pict-o-word
- Repository: https://github.com/femitun/pict-o-word

## Overview

##### Project type and purpose
- This is a stand-alone Python “pict-o-word” puzzle game (Dreamscapes competition entry).
- Users navigate menus (home, loading), play rounds of picture-based word puzzles across three difficulty levels, spend or earn coins, and trigger sounds/music.

##### File structure
Top-level components:
- Entry & navigation scripts: main1.py, home_page.py, loading_page.py
- In-game UI & logic: Ingame_ui.py, game_ui.py, coin_manager.py
- Puzzle definitions:
- Flat files games/Easy#.py, Medium#.py, Hard#.py (individual puzzle rounds)
- Organized subpackages games/easy/, games/medium/, games/hard/ (categories of puzzles)
- Assets: audio files (.wav, .mp3), Nerko_One font directory
- Misc: .gitignore, IDE settings, README

##### README
- Very brief; confirms project name (“pict-o-word”) and competition context.

##### Core components to model
a. Frontend/UI Layer
- main1.py (app entry)
- home_page.py (main menu)
- loading_page.py (pre-round loader)
- Ingame_ui.py & game_ui.py (render puzzles, accept input)
b. Game Logic Layer
- coin_manager.py (track coins, enforce spends/earnings)
- Puzzle modules (games/Easy#.py, Medium#.py, Hard#.py) + category packages
c. Asset Manager
- Audio subsystem for sound effects and background music
- Font loader (Nerko_One)
d. Data Store (if any persistent state)
- In-memory objects or simple file I/O (no database shown)
e. External Resources
- OS file system for assets
- Potential future API or high-score server (none present now)

##### Relationships & interactions
- Startup: main1.py → home_page.py
- User selects difficulty → loading_page.py → Ingame_ui.py
- Ingame_ui.py invokes game_ui.py to render puzzle
- game_ui.py pulls puzzle data from the appropriate games/Easy#.py (or Medium#/Hard#) module
- game_ui.py calls coin_manager.py to check/update coin balance
- UI triggers audio subsystem (play hint sound, win/lose sounds, background mp3)
- On round end: game_ui.py → home_page.py (or repeat cycle)

##### Architectural patterns & principles
- Layered separation: UI layer (presentation) vs. logic layer (game rules, coin management) vs. asset management
- Modular puzzle definitions (each round is a self-contained Python module)
- Package grouping by difficulty/category

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        MainApp["Main App Entry\n(main1.py)"]:::ui
        HomeUI["Home/Menu UI\n(home_page.py)"]:::ui
        LoadingUI["Loading Screen UI\n(loading_page.py)"]:::ui
        InGameUI["In-Game UI Renderer\n(Ingame_ui.py)"]:::ui
        GameUI["Game Logic & Rendering UI\n(game_ui.py)"]:::ui
    end

    %% Logic Layer
    subgraph "Logic Layer"
        CoinManager["Coin Management Service\n(coin_manager.py)"]:::logic
        subgraph "Puzzle Modules"
            subgraph "Easy Puzzles"
                EasyTop["Top-level Easy Scripts"]:::logic
                easyDir["Easy Package"]:::logic
            end
            subgraph "Medium Puzzles"
                MediumTop["Top-level Medium Scripts"]:::logic
                mediumDir["Medium Package"]:::logic
            end
            subgraph "Hard Puzzles"
                HardTop["Top-level Hard Scripts"]:::logic
                hardDir["Hard Package"]:::logic
            end
        end
    end

    %% Assets Layer
    subgraph "Assets"
        AudioManager["Audio Asset Manager\n(.wav, .mp3)"]:::asset
        FontLoader["Font Assets\n(Nerko_One/)"]:::asset
    end

    %% Connections
    MainApp -->|"start()"| HomeUI
    HomeUI -->|"selectDifficulty()"| LoadingUI
    LoadingUI -->|"loadPuzzle()"| InGameUI
    InGameUI -->|"renderPuzzle()"| GameUI
    GameUI -->|"getPuzzle()"| EasyTop
    GameUI -->|"getPuzzle()"| MediumTop
    GameUI -->|"getPuzzle()"| HardTop
    GameUI -->|"updateCoins()"| CoinManager
    InGameUI -->|"playSound()"| AudioManager
    GameUI -->|"endRound()"| HomeUI

    %% Click Events
    click MainApp "https://github.com/femitun/pict-o-word/blob/main/main1.py"
    click HomeUI "https://github.com/femitun/pict-o-word/blob/main/home_page.py"
    click LoadingUI "https://github.com/femitun/pict-o-word/blob/main/loading_page.py"
    click InGameUI "https://github.com/femitun/pict-o-word/blob/main/Ingame_ui.py"
    click GameUI "https://github.com/femitun/pict-o-word/blob/main/game_ui.py"
    click CoinManager "https://github.com/femitun/pict-o-word/blob/main/coin_manager.py"
    click EasyTop "https://github.com/femitun/pict-o-word/blob/main/games/Easy1.py"
    click easyDir "https://github.com/femitun/pict-o-word/tree/main/games/easy/"
    click MediumTop "https://github.com/femitun/pict-o-word/blob/main/games/Medium1.py"
    click mediumDir "https://github.com/femitun/pict-o-word/tree/main/games/medium/"
    click HardTop "https://github.com/femitun/pict-o-word/blob/main/games/Hard1.py"
    click hardDir "https://github.com/femitun/pict-o-word/tree/main/games/hard/"
    click AudioManager "https://github.com/femitun/pict-o-word/blob/main/click_sound.wav"
    click FontLoader "https://github.com/femitun/pict-o-word/tree/main/Nerko_One/"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef logic fill:#9ff,stroke:#333,stroke-width:1px
    classDef asset fill:#ff9,stroke:#333,stroke-width:1px
```
