# dolphinsan/fplbegiga architecture

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

- Interactive diagram: https://gitdiagram.com/dolphinsan/fplbegiga
- Repository: https://github.com/dolphinsan/fplbegiga

## Overview

##### Project type & purpose (from README + file tree)
This is a **single-process Python game**: “Nested Endless TicTacToe” (Ultimate-TTT-like) with a **score-based endless loop** and a **dynamic reset mechanic** when a big-board line is won.

**Entrypoint / runnable script** is very likely:
- `TTT.py` (README explicitly references running it)

Core modules inferred by filenames:
- `Game.py`: game loop + global state orchestration (turns, active board rules, scoring, pause/restart/quit).
- `TTT.py`: UI/bootstrap; likely creates a `Game` instance and runs input/render loop.
- `Game_Design_Document_FP_LBE_GIGA.pdf`: specification reference (mechanics/requirements).
- `__pycache__/`: runtime artifact.

##### Evaluate
- update active board target based on tile position
- check big-board line of won small boards
##### Big win handling (if triggered)
- award score (+25)
- flash winning line (0.3s)
- reset only the 3 small boards in that winning line
- set “free choice” for next player

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1 — Container/Runtime View
%% =========================
subgraph D1["Diagram 1 — Runtime (Single Process Game Loop)"]
direction TB

P["Python Process: Nested Endless TicTacToe"]:::proc

subgraph RUNTIME["Runtime Components"]
direction TB

UI["TTT.py\n(UI + Entry/Main Loop)"]:::ui
subgraph UI_SUB["UI / Presentation (TTT.py)"]
direction TB
UI_Input["Input Handler\n(click/pause/restart/quit)"]:::ui
UI_Render["Renderer\n(boards/highlights/score)"]:::ui
end

ENG["Game.py\n(Game Engine / Orchestrator)"]:::engine
subgraph ENG_SUB["Game Engine Internals (logical components in Game.py)"]
direction TB
TurnMgr["Turn Manager\n(X/O)"]:::engine
ActiveRule["Active-Board Rule\n(constrained/free-choice)"]:::engine
Validator["Move Validator"]:::engine
ScoreMgr["Score Manager\n(+25 big win; diff>=100)"]:::score
BigWinEval["Big-Board Win Evaluator\n(3 won boards in a line)"]:::special
ResetCtl["Reset Controller\n(reset 3 boards in winning line;\nreset draws per spec)"]:::special
PauseSM["Pause/Restart/Quit\nState Machine"]:::state
FlashTimer["Win Flash Timer\n(0.3s line flash)"]:::special
end

DOM["SmallBoard.py\n(Domain Rules)"]:::domain
subgraph BOARDS["Small Boards (in-memory)"]
direction TB
SB0["SmallBoard[0]"]:::domain
SB1["SmallBoard[1]"]:::domain
SB2["SmallBoard[2]"]:::domain
SB3["SmallBoard[3]"]:::domain
SB4["SmallBoard[4]"]:::domain
SB5["SmallBoard[5]"]:::domain
SB6["SmallBoard[6]"]:::domain
SB7["SmallBoard[7]"]:::domain
SB8["SmallBoard[8]"]:::domain
end

end

SPEC["Game Design Doc (PDF)\nMechanics/Requirements"]:::doc
README["README\nRun Instructions/Overview"]:::doc

P -->|"runs"| UI
UI -->|"creates/uses"| ENG
ENG -->|"owns 9x"| BOARDS
DOM -->|"defines class"| BOARDS

UI_Input -->|"dispatches action"| ENG
ENG -->|"returns render state"| UI_Render

README -.->|"describes running"| UI
SPEC -.->|"specifies mechanics"| ENG
end

%% =========================
%% Diagram 2 — Module/Class Dependency View
%% =========================
subgraph D2["Diagram 2 — Module/Class Relationships (Dependencies + Ownership)"]
direction TB

TTTMod["TTT.py\n(entrypoint)"]:::ui
GameMod["Game.py\n(Game class + orchestration)"]:::engine
SmallMod["SmallBoard.py\n(SmallBoard class)"]:::domain

GameObj["Game\n(instance)"]:::engine
ScoreState["Score State\n(X_score, O_score)"]:::score
ActiveState["Active Board State\n(target/free-choice)"]:::engine
BigState["Big-Board State\n(won-board map/line)"]:::special
PauseState["Mode State\n(Playing/Paused/BigWin/Over)"]:::state

TTTMod -->|"imports/uses"| GameMod
GameMod -->|"imports/uses"| SmallMod

TTTMod -->|"instantiates"| GameObj
GameObj -->|"has-a"| ScoreState
GameObj -->|"has-a"| ActiveState
GameObj -->|"has-a"| BigState
GameObj -->|"has-a"| PauseState

GameObj -->|"has-a (list[9])"| SB0
end

%% =========================
%% Diagram 3 — Move → BigWin → Flash → Selective Reset (flow form)
%% =========================
subgraph D3["Diagram 3 — Sequence (Move → BigWin → Flash → Selective Reset)"]
direction TB

PlayerN["Player"]:::ui
UISeq["TTT.py (UI Loop)"]:::ui
GameSeq["Game.py (Game Engine)"]:::engine
SBSeq["SmallBoard.py (SmallBoard instance)"]:::domain
Flash["Win Flash Timer (0.3s)"]:::special

S1["Select tile\n(board idx + cell)"]:::ui
S2["handle_action(place_mark)"]:::engine
S3["Validate move\n(active-board rule / free-choice)"]:::engine
S4["place_mark(r,c,current_player)"]:::domain
S5["check_win_or_draw()\n→ small_state (win/draw/ongoing)"]:::domain
S6["Update next active board\n(cell → target)"]:::engine
S7["Evaluate big-board line\nof won boards"]:::special

W1["If big-board win detected"]:::special
W2["Score += 25 (winner)"]:::score
W3["trigger_flash(winning_line)"]:::special
W4["after 0.3s"]:::special
W5["reset 3 small boards\nin winning line"]:::special
W6["set free-choice\nfor next player"]:::engine

N1["Else: continue normal\nturn progression"]:::engine

V1["Victory check\nabs(score diff) >= 100?"]:::score
R1["get_render_state()"]:::ui
R2["Render boards/highlights/scores"]:::ui

PlayerN --> S1 --> UISeq
UISeq --> S2 --> GameSeq
GameSeq --> S3
GameSeq --> S4 --> SBSeq
SBSeq --> S5 --> GameSeq
GameSeq --> S6 --> S7 --> W1

W1 -->|"Yes"| W2 --> W3 --> Flash
Flash --> W4 --> GameSeq
GameSeq --> W5 --> W6 --> V1

W1 -->|"No"| N1 --> V1

V1 --> R1 --> UISeq --> R2 --> PlayerN
end

%% =========================
%% Click Events (from component_mapping)
%% =========================
click UI "https://github.com/dolphinsan/fplbegiga/blob/main/TTT.py"
click TTTMod "https://github.com/dolphinsan/fplbegiga/blob/main/TTT.py"

click ENG "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click GameMod "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click GameObj "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click TurnMgr "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click ActiveRule "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click Validator "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click ScoreMgr "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click BigWinEval "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click ResetCtl "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click PauseSM "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click FlashTimer "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click GameSeq "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"
click Flash "https://github.com/dolphinsan/fplbegiga/blob/main/Game.py"

click DOM "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SmallMod "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB0 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB1 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB2 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB3 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB4 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB5 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB6 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB7 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SB8 "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"
click SBSeq "https://github.com/dolphinsan/fplbegiga/blob/main/SmallBoard.py"

click SPEC "https://github.com/dolphinsan/fplbegiga/blob/main/Game_Design_Document_FP_LBE_GIGA.pdf"
click README "https://github.com/dolphinsan/fplbegiga/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef proc fill:#111827,stroke:#0f172a,color:#f9fafb,stroke-width:2px;
classDef ui fill:#2563eb,stroke:#1e3a8a,color:#ffffff,stroke-width:1.5px;
classDef engine fill:#10b981,stroke:#065f46,color:#052e1d,stroke-width:1.5px;
classDef domain fill:#a78bfa,stroke:#5b21b6,color:#1f1147,stroke-width:1.5px;
classDef special fill:#f59e0b,stroke:#92400e,color:#1f1300,stroke-width:1.5px;
classDef score fill:#22c55e,stroke:#166534,color:#052e1d,stroke-width:1.5px;
classDef state fill:#f43f5e,stroke:#9f1239,color:#ffffff,stroke-width:1.5px;
classDef doc fill:#64748b,stroke:#334155,color:#0b1220,stroke-width:1.5px;
```
