# sanusmxgame/thimbles-ai-tool architecture

> Architecture diagram of the GitHub repository sanusmxgame/thimbles-ai-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanusmxgame/thimbles-ai-tool
- Repository: https://github.com/sanusmxgame/thimbles-ai-tool

## Overview

##### Project Type and Purpose
- Type: Browser-side AI / computer-vision helper tool with an optional local simulator
- Purpose:
– Live overlay on third-party Thimbles games via a Tampermonkey user script
– Offline/local simulation via static files and a minimal Python server

##### Main Components
a. Client Browser Environment
- Tampermonkey extension (runs the user script)
- Native JavaScript environment (index.html + logic.js + tracking.js)
- TensorFlow.js integration for ML inference
b. User Script Layer
- thimbles-cup-highlighter.user.js (injected into the target page)
- Hooks into the DOM, captures canvas frames, calls the detection logic
c. Core Logic & Tracking
- logic.js – prediction orchestration (cup location + provably-fair decoding)
- tracking.js – frame-by-frame canvas analysis and visual tracking routines
d. Offline Simulation
- index.html + style.css – a self-contained UI for simulating the game
- simulator.js – reads data/incoming.json, feeds frames into tracking.js
- data/incoming.json – canned game frames and metadata
- server.py – Python’s `http.server` to host the static assets
e. External Dependencies
- TensorFlow.js (for optional training and inference)
- Tampermonkey (script injection)

##### Relationships & Data Flows
- Live Mode Flow:
1. User navigates to Odds96 Thimbles game
2. Tampermonkey script injects thimbles-cup-highlighter.user.js
3. Script captures the canvas element’s frames
4. Frames > tracking.js → identifies cup positions
5. logic.js decodes “provably fair” data & runs TensorFlow.js model
6. Overlay highlights the correct cup in real time
- Offline Mode Flow:
1. User runs `python -m http.server` (server.py)
2. Browser loads index.html + style.css
3. simulator.js reads data/incoming.json
4. simulator.js pipelines frames through tracking.js & logic.js
5. UI displays results on the local page

##### Architectural Patterns & Principles
- Modular separation between:
– Script injection layer (Tampermonkey)
– Core detection logic (logic.js + tracking.js)
– Data source layer (live canvas vs. incoming.json)
- Clear extension points: swap in different ML models (TensorFlow.js), plug in new simulation data
- Single responsibility per file:
– `tracking.js` only handles computer-vision tasks
– `logic.js` orchestrates flow and ML interactions
– `simulator.js` abstracts offline data feeding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Environment
    subgraph "Client Browser Environment"
        direction TB
        Canvas["Game Canvas"]:::client
        UI["index.html + style.css"]:::client
    end

    %% User Script Layer
    subgraph "User Script Layer"
        direction TB
        Script["thimbles-cup-highlighter.user.js"]:::script
    end

    %% Core Logic & Tracking
    subgraph "Core Logic & Tracking"
        direction TB
        Track["tracking.js"]:::core
        Logic["logic.js"]:::core
    end

    %% Simulation & Server
    subgraph "Simulation & Server"
        direction TB
        Simulator["simulator.js"]:::sim
        Data["data/incoming.json"]:::sim
        Server["server.py"]:::sim
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TF["TensorFlow.js"]:::external
        TM["Tampermonkey"]:::external
    end

    %% Live Mode Flow
    TM -->|"injects script"| Script
    Script -->|"captures canvas frame"| Canvas
    Canvas -->|"canvas frame"| Track
    Track -->|"analysis results"| Logic
    Logic -->|"highlight overlay"| Canvas
    Logic -->|"inference calls"| TF
    TF -->|"inference results"| Logic

    %% Offline Mode Flow
    Server -->|"hosts UI & assets"| UI
    UI -->|"load simulator.js & style.css"| Simulator
    Simulator -->|"reads data"| Data
    Simulator -->|"canvas frame"| Track
    Track -->|"analysis results"| Logic
    Logic -->|"display results"| UI
    Logic -->|"inference calls"| TF

    %% Click Events
    click UI "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/index.html"
    click UI "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/style.css"
    click Script "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/thimbles-cup-highlighter.user.js"
    click Track "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/tracking.js"
    click Logic "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/logic.js"
    click Simulator "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/simulator.js"
    click Data "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/data/incoming.json"
    click Server "https://github.com/sanusmxgame/thimbles-ai-tool/blob/main/server.py"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef script fill:#FFE5B4,stroke:#D2691E,color:#D2691E;
    classDef core fill:#DFFFD0,stroke:#228B22,color:#228B22;
    classDef sim fill:#E0E0E0,stroke:#888888,color:#444444;
    classDef external fill:#F3E5F5,stroke:#6A0DAD,color:#6A0DAD
```
