# adityakamat24/wordlebot architecture

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

- Interactive diagram: https://gitdiagram.com/adityakamat24/wordlebot
- Repository: https://github.com/adityakamat24/wordlebot

## Overview

##### Main Components
- User Interface:
- Gradio-based interactive UI that mimics the Wordle layout.

- Game Logic & Solver Engine:
- Core logic within app.py that handles reading valid words from wordle.csv, initializing the game, computing feedback (gray, yellow, green), and executing candidate pruning.
- Use of algorithms like frequency-based heuristics and the scoring mechanism that considers historical data.

- Feedback Mechanism:
- Feedback computation process—from the guess versus secret comparison to setting the proper states (green, yellow, gray).

- Data Visualization:
- Components that generate interactive visualizations (heatmap for letter frequencies and confidence chart), which help users understand the impact of candidate filtering after each guess.

- Qdrant Integration:
- Logging component where game data (guesses, feedback, candidate counts) are pushed to Qdrant.
- How the historical logs impact the candidate scoring for future guesses.

- CSV Data Loader:
- A distinct component for loading valid words from the CSV file (wordle.csv) that seeds candidate words for the solver.

- External Dependencies & Environment:
- External configuration like the Qdrant API key requirement and the installation/setup environment (as defined in requirements.txt).

##### Relationships and Data Flow
- Upon starting, the game logic in app.py is initialized:
- It loads words from wordle.csv.
- It sets the initial guess.
- The UI displays the state and receives user interactions and feedback.
- Once feedback is submitted:
- The feedback computation component calculates the results.
- The candidate pruning mechanism refines the list of potential words.
- Qdrant logging records each game state and guess, feeding historical bonus data back into the solver.
- Updated visualizations (heatmap and confidence chart) are generated and displayed via the UI.
- The cycle repeats until the correct guess is confirmed.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Different components handle UI rendering, business logic computations, data visualization, and external service integrations.
- Modular Design:
- Even though the entire logic is mostly in app.py, its internal structure can be thought of in modular terms (initialization, feedback processing, candidate selection, logging).
- Data-Driven Decision Making:
- The algorithm uses both current candidate frequency and historical data (via Qdrant) for selecting the best guess.
- Caching:
- Leverage LRU caching to optimize repeated feedback calculations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    CSV["CSV Data Loader (wordle.csv)"]:::data
    Solver["Wordle Solver Logic"]:::logic
    UI["User Interface (Gradio)"]:::ui
    Feedback["Feedback Processor"]:::logic
    Qdrant["Historical Data Logger (Qdrant Integration)"]:::external
    Visualization["Data Visualizations (Heatmap & Confidence Chart)"]:::ui
    External["External Dependencies & Environment Setup"]:::external

    %% Flow Connections
    CSV -->|"loads_words"| Solver
    External -->|"env_setup"| Solver
    Solver -->|"initial_guess_and_state"| UI
    UI -->|"submit_feedback"| Feedback
    Feedback -->|"update_candidates"| Solver
    Solver -->|"log_game_state"| Qdrant
    Qdrant -->|"historical_data"| Solver
    Solver -->|"generate_visuals"| Visualization
    Visualization -->|"render_charts"| UI

    %% Click Events
    click CSV "https://github.com/adityakamat24/wordlebot/blob/main/wordle.csv"
    click Solver "https://github.com/adityakamat24/wordlebot/blob/main/app.py"
    click UI "https://github.com/adityakamat24/wordlebot/blob/main/app.py"
    click Visualization "https://github.com/adityakamat24/wordlebot/blob/main/app.py"
    click Qdrant "https://github.com/adityakamat24/wordlebot/blob/main/app.py"
    click External "https://github.com/adityakamat24/wordlebot/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef logic fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef data fill:#A9DFBF,stroke:#117864,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#78281F,stroke-width:2px;
```
