# pelipeli2/s194749wheeloffortune architecture

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

- Interactive diagram: https://gitdiagram.com/pelipeli2/s194749wheeloffortune
- Repository: https://github.com/pelipeli2/s194749wheeloffortune

## Overview

This repo is a **single-module Android application** written in **Kotlin**, implementing a “Wheel of Fortune”-style word guessing game. Architecturally it’s a **client-only/offline app**: there is **no backend**, no database, and no external services. The core of the system is a **Fragment-based UI flow** orchestrated by **Jetpack Navigation**, with most game state and business logic implemented directly inside `GameFragment`.

- **Runtime container**: Android OS → App process
- **UI host**: `MainActivity` + `NavHostFragment`
- **Screens (Fragments)** and **navigation graph**
- **Game logic + state** (lives, score, current word/category, guessed letters)
- **Resources** (layouts, strings) that the UI depends on
- **Build/dependency layer** (Gradle, AndroidX, Navigation)

##### File structure analysis (what to map into components)
From the tree + README, the meaningful architectural units are:

##### Application module
- `app/` (single Android app module)
- `src/main/java/...`
- `MainActivity.kt` (activity host)
- `TitleFragment.kt` (start screen)
- `GameFragment.kt` (main logic)
- `wonGame.kt` (win screen)
- `Lostgame.kt` (lose screen)
- `src/main/res/`
- `layout/` → `activity_main.xml`, fragment layouts
- `navigation/navigation.xml` → navigation graph (key architectural artifact)
- `AndroidManifest.xml` (app entry + activity declaration)

##### Build / tooling
- Root `build.gradle`, `settings.gradle`, `gradle/wrapper/*`
- App `app/build.gradle` (dependencies: AndroidX, Navigation KTX, etc.)

##### Tests
- `src/test` unit test scaffold
- `src/androidTest` instrumented test scaffold

##### README-derived architecture cues
The README explicitly defines the **screen flow**:
##### win/lose → return to title

It also flags an important design constraint:
- **Word lists/categories are hardcoded** in `GameFragment` (so “data source” is in-memory, local)

##### Concrete checklist of what to include (to be “very detailed”)

**Nodes**
- Android OS
- MainActivity
- activity_main.xml
- NavHostFragment
- navigation.xml
- TitleFragment + fragment_title.xml
- GameFragment + fragment_game.xml
- wonGame + fragment_won_game.xml
- Lostgame + fragment_lostgame.xml
- GameFragment subnodes:
- Category/Word Lists (hardcoded)
- RNG / Wheel Outcome
- Guess Validator
- Score/Lives/Mask State (in-memory)
- Win/Lose Evaluator

**Edges**
- OS → MainActivity (launch)
- MainActivity → NavHostFragment (host)
- NavHostFragment → navigation.xml (reads graph)
- navigation.xml → each Fragment (destination mapping)
- Each Fragment → its layout (inflate)
- TitleFragment → GameFragment (Start)
- GameFragment → wonGame (win)
- GameFragment → Lostgame (lose)
- wonGame → TitleFragment (play again)
- Lostgame → TitleFragment (try again)
- GameFragment: Spin/Guess → state update → UI update → win/lose decision

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= View 1: Container + UI Navigation =========
    subgraph V1["View 1 — Runtime Container + UI Navigation (Single-Activity, Fragment-based)"]
        direction TB

        OS["Android OS"]:::platform

        subgraph APK["App Process / APK (Kotlin, AndroidX)"]
            direction TB

            MAN["AndroidManifest.xml\n(App entry + MainActivity declaration)"]:::resource

            subgraph UIHOST["UI Host"]
                direction TB
                MA["MainActivity\n(AndroidX AppCompat Activity)"]:::ui
                AML["activity_main.xml\n(contains NavHostFragment)"]:::resource
                NH["NavHostFragment\n(Jetpack Navigation runtime)"]:::nav
            end

            subgraph NAV["Navigation Orchestration"]
                direction TB
                NG["navigation.xml\n(Nav Graph: Title → Game → Win/Lose → Title)"]:::nav
            end

            subgraph SCREENS["Screens (Fragments)"]
                direction TB
                TF["TitleFragment\n(Start screen)"]:::ui
                TFL["fragment_title.xml"]:::resource

                GF["GameFragment\n(Core game logic + state)"]:::ui
                GFL["fragment_game.xml"]:::resource

                WF["wonGame Fragment\n(Win screen)"]:::ui
                WFL["fragment_won_game.xml"]:::resource

                LF["Lostgame Fragment\n(Lose screen)"]:::ui
                LFL["fragment_lostgame.xml"]:::resource
            end

            subgraph RES["Shared UI Resources"]
                direction TB
                STR["strings.xml"]:::resource
                COL["colors.xml"]:::resource
                THD["themes.xml (day)"]:::resource
                THN["themes.xml (night)"]:::resource
            end

            subgraph BUILD["Build / Dependencies"]
                direction TB
                RBG["Root build.gradle\n(Gradle + Android plugin config)"]:::build
                SET["settings.gradle"]:::build
                ABG["app/build.gradle\n(Dependencies: AndroidX, Navigation KTX)"]:::build
                GWP["gradle-wrapper.properties"]:::build
            end

            subgraph TESTS["Test Harness (Scaffold)"]
                direction TB
                UTEST["ExampleUnitTest.kt\n(Unit test scaffold)"]:::test
                ATEST["ExampleInstrumentedTest.kt\n(Instrumented test scaffold)"]:::test
            end
        end

        %% Runtime startup / hosting
        OS -->|"launches"| MAN
        MAN -->|"declares entry Activity"| MA
        MA -->|"inflates"| AML
        AML -->|"hosts"| NH
        NH -->|"reads graph"| NG

        %% Nav graph destinations
        NG -->|"startDestination"| TF
        NG -->|"destination"| GF
        NG -->|"destination"| WF
        NG -->|"destination"| LF

        %% Navigation actions (screen flow)
        TF -->|"StartButton:navigate"| GF
        GF -->|"WinRule:navigate"| WF
        GF -->|"LoseRule:navigate"| LF
        WF -->|"PlayAgain:navigate"| TF
        LF -->|"TryAgain:navigate"| TF

        %% Resource dependencies (compile/runtime inflate)
        MA -.->|"uses layout"| AML

        TF -.->|"inflates"| TFL
        GF -.->|"inflates"| GFL
        WF -.->|"inflates"| WFL
        LF -.->|"inflates"| LFL

        TF -.->|"uses"| STR
        GF -.->|"uses"| STR
        WF -.->|"uses"| STR
        LF -.->|"uses"| STR

        TF -.->|"theme/colors"| THD
        GF -.->|"theme/colors"| THD
        WF -.->|"theme/colors"| THD
        LF -.->|"theme/colors"| THD
        THD -.->|"uses"| COL
        THN -.->|"uses"| COL

        %% Build relationships
        SET -->|"includes module"| ABG
        RBG -->|"configures"| ABG
        GWP -->|"pins Gradle wrapper"| RBG
    end

    %% ========= View 2: GameFragment internal architecture =========
    subgraph V2["View 2 — GameFragment Internal Components (Logic + In-Memory State)"]
        direction TB

        USER["Player\n(Taps Spin, enters Letter guess)"]:::external

        subgraph GFZ["GameFragment (zoom-in)"]
            direction TB

            INSPIN["Spin Button Handler"]:::logic
            INGUESS["Letter Input Handler"]:::logic

            WHEEL["RNG / Wheel Outcome\n(500/1000/2000/extra life/bankrupt/missed turn)"]:::logic
            WORDS["Category + Word Lists\n(Hardcoded: Countries/Sports/Cars)"]:::logic

            STATE["In-Memory Game State\nLives(5), Score, SecretWord+Mask, GuessedLetters"]:::state

            VALID["Guess Evaluator\n(present? already guessed?)"]:::logic
            RULES["Rule Engine\n(apply spin/guess effects)"]:::logic
            END["Win/Lose Evaluator\n(all revealed? lives<1?)"]:::logic

            RENDER["UI Render Update\n(masked word, lives, score, messages)"]:::ui
            NAVOUT["Navigation Events\n(navigate to wonGame / Lostgame)"]:::nav
        end

        %% Inputs
        USER -->|"tap Spin"| INSPIN
        USER -->|"enter guess"| INGUESS

        %% Spin path
        INSPIN -->|"generate outcome"| WHEEL
        WHEEL -->|"updates"| RULES

        %% Guess path
        INGUESS -->|"validate"| VALID
        VALID -->|"updates"| RULES

        %% Word source + state
        WORDS -->|"selects secret word/category"| STATE
        RULES -->|"mutates"| STATE

        %% Rendering + end-state navigation
        STATE -->|"drives"| RENDER
        STATE -->|"checked by"| END
        END -->|"if win/lose"| NAVOUT

        %% Link back to View 1 fragments for clarity
        NAVOUT -->|"win"| WF
        NAVOUT -->|"lose"| LF
    end

    %% ========= Click Events (from component_mapping) =========
    click APK "https://github.com/pelipeli2/s194749wheeloffortune/tree/master/app/"
    click MAN "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/AndroidManifest.xml"
    click MA "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/java/com/example/s194749wheeloffortune/MainActivity.kt"
    click AML "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/layout/activity_main.xml"
    click NG "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/navigation/navigation.xml"
    click TF "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/java/com/example/s194749wheeloffortune/TitleFragment.kt"
    click TFL "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/layout/fragment_title.xml"
    click GF "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/java/com/example/s194749wheeloffortune/GameFragment.kt"
    click GFL "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/layout/fragment_game.xml"
    click WF "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/java/com/example/s194749wheeloffortune/wonGame.kt"
    click WFL "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/layout/fragment_won_game.xml"
    click LF "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/java/com/example/s194749wheeloffortune/Lostgame.kt"
    click LFL "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/layout/fragment_lostgame.xml"
    click STR "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/values/strings.xml"
    click THD "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/values/themes.xml"
    click THN "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/values-night/themes.xml"
    click COL "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/main/res/values/colors.xml"
    click ABG "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/build.gradle"
    click RBG "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/build.gradle"
    click SET "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/settings.gradle"
    click GWP "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/gradle/wrapper/gradle-wrapper.properties"
    click UTEST "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/test/java/com/example/s194749wheeloffortune/ExampleUnitTest.kt"
    click ATEST "https://github.com/pelipeli2/s194749wheeloffortune/blob/master/app/src/androidTest/java/com/example/s194749wheeloffortune/ExampleInstrumentedTest.kt"

    %% ========= Styles =========
    classDef platform fill:#1f2937,stroke:#0b1220,color:#ffffff,stroke-width:1.5px
    classDef external fill:#111827,stroke:#334155,color:#e5e7eb,stroke-width:1.2px
    classDef ui fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:1.5px
    classDef nav fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1.5px
    classDef resource fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px
    classDef logic fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px
    classDef state fill:#22c55e,stroke:#166534,color:#052e16,stroke-width:2px,stroke-dasharray: 6 4
    classDef build fill:#64748b,stroke:#334155,color:#ffffff,stroke-width:1.2px
    classDef test fill:#94a3b8,stroke:#475569,color:#0f172a,stroke-width:1.2px
```
