# byte-hunting/puzzle_net architecture

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

- Interactive diagram: https://gitdiagram.com/byte-hunting/puzzle_net
- Repository: https://github.com/byte-hunting/puzzle_net

## Overview

##### Project type and purpose
- From the file tree, this is a full-stack web application with:
- A Python “backend” (app.py, embeddings.py, search_similar.py, generate_embedding.py, utils, notebooks).
- A React “frontend” in the client/ directory (Vite + JSX components under client/src).
- Purpose: host and display chess puzzles, generate and store embeddings for similarity search, serve puzzles via a REST API, and allow users to browse/search puzzles in a grid UI.

##### File structure
Top-level:
- app.py – entry point for the web server/API.
- embeddings.py, generate_embedding.py, search_similar.py – scripts and modules for generating puzzle embeddings and searching by similarity.
- utils/fen_to_image.py – utility to render FEN strings as images.
- notebooks/parse_puzzles.ipynb – Jupyter notebook to parse raw puzzle data.
- requirements.txt – Python dependencies (Flask/FastAPI, embedding/vector libraries).
- build_index.py, clean_script.py – build and cleanup scripts for preprocessing or indexing.

client/:
- package.json, vite.config.js, eslint.config.js – React build/config.
- public/index.html – single-page app host.
- src/ – React components:
– PuzzlesGrid, PuzzleCard, PuzzleModal, MiniBoard (UI for displaying puzzles)
– api.js (client-side wrappers around backend HTTP calls)
– App.jsx – root React component.

##### (empty) README
- No additional architecture notes, so we infer from filenames and directory conventions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (React Frontend)"
        direction TB
        Browser["User Browser"]:::frontend
        MainJS["main.jsx"]:::frontend
        AppJS["App.jsx"]:::frontend
        APIJS["api.js"]:::frontend
        GridComp["PuzzlesGrid.jsx"]:::frontend
        CardComp["PuzzleCard.jsx"]:::frontend
        ModalComp["PuzzleModal.jsx"]:::frontend
        MiniBoardComp["MiniBoard.jsx"]:::frontend
    end

    %% Server Layer
    subgraph "Server (Python API)"
        direction TB
        APIServer["app.py"]:::backend
        subgraph "Business Logic"
            direction TB
            EmbeddingsMod["embeddings.py"]:::backend
            GenEmbed["generate_embedding.py"]:::backend
            SearchMod["search_similar.py"]:::backend
            FenUtil["utils/fen_to_image.py"]:::backend
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        PuzzleStore["Puzzle Data Store"]:::datastore
        SearchIndex["Embeddings Index (FAISS/Pinecone)"]:::datastore
    end

    %% Offline ETL
    subgraph "Offline Pipeline"
        direction TB
        Notebook["parse_puzzles.ipynb"]:::offline
        CleanScript["clean_script.py"]:::offline
        BuildIndex["build_index.py"]:::offline
    end

    %% Relationships
    Browser -->|"loads SPA"| MainJS
    MainJS --> AppJS
    AppJS --> GridComp
    GridComp --> CardComp
    CardComp --> ModalComp
    ModalComp --> MiniBoardComp

    AppJS -->|"calls GET /api/puzzles"| APIJS
    AppJS -->|"calls POST /api/search"| APIJS
    APIJS --> APIServer

    APIServer --> EmbeddingsMod
    APIServer --> SearchMod
    APIServer --> FenUtil
    SearchMod --> SearchIndex
    EmbeddingsMod --> SearchIndex
    APIServer --> PuzzleStore
    FenUtil --> PuzzleStore

    Notebook --> CleanScript
    CleanScript --> GenEmbed
    GenEmbed --> BuildIndex
    BuildIndex --> SearchIndex
    BuildIndex --> PuzzleStore

    %% Click Events
    click MainJS "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/main.jsx"
    click AppJS "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/App.jsx"
    click APIJS "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/api.js"
    click GridComp "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/components/PuzzlesGrid.jsx"
    click CardComp "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/components/PuzzleCard.jsx"
    click ModalComp "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/components/PuzzleModal.jsx"
    click MiniBoardComp "https://github.com/byte-hunting/puzzle_net/blob/main/client/src/components/MiniBoard.jsx"
    click APIServer "https://github.com/byte-hunting/puzzle_net/blob/main/app.py"
    click EmbeddingsMod "https://github.com/byte-hunting/puzzle_net/blob/main/embeddings.py"
    click GenEmbed "https://github.com/byte-hunting/puzzle_net/blob/main/generate_embedding.py"
    click SearchMod "https://github.com/byte-hunting/puzzle_net/blob/main/search_similar.py"
    click FenUtil "https://github.com/byte-hunting/puzzle_net/blob/main/utils/fen_to_image.py"
    click Notebook "https://github.com/byte-hunting/puzzle_net/blob/main/notebooks/parse_puzzles.ipynb"
    click CleanScript "https://github.com/byte-hunting/puzzle_net/blob/main/clean_script.py"
    click BuildIndex "https://github.com/byte-hunting/puzzle_net/blob/main/build_index.py"
    click PuzzleStore "https://github.com/byte-hunting/puzzle_net/blob/main/requirements.txt"
    click SearchIndex "https://github.com/byte-hunting/puzzle_net/blob/main/client/package.json"
    click SearchIndex "https://github.com/byte-hunting/puzzle_net/blob/main/client/vite.config.js"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,stroke-width:2px
    classDef backend fill:#E6FFEA,stroke:#28a745,stroke-width:2px
    classDef datastore fill:#FFF4D6,stroke:#d69f12,stroke-width:2px
    classDef offline fill:#F0F0F0,stroke:#6a737d,stroke-width:2px
```
