# jairejustin/woodpecker-chess architecture

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

- Interactive diagram: https://gitdiagram.com/jairejustin/woodpecker-chess
- Repository: https://github.com/jairejustin/woodpecker-chess

## Overview

##### Project Type & Purpose
- This is a single-page, front-end React/TypeScript application (“Woodpecker Chess”) built with Vite.
- Purpose: provide a chess training UI where users solve Lichess-sourced tactical puzzles, track progress via playlists, and (eventually) incorporate spaced-repetition and analytics.

##### File-Structure Analysis
- Top-level:
- README.md, .gitignore
- frontend/ (entire codebase)
- frontend/ holds:
- public/: static assets & puzzles_samples.json (temporary local puzzle store)
- src/: UI code
– components/: reusable React components (ChessBoard, Sidebar, PlaylistViewer, etc.)
– pages/: route-level components (HomePage, LoginPage, PuzzleExplorerPage…)
– api/: fetch wrappers for puzzles & playlists
– context/: SessionContext for auth/session state
– hooks/: custom hooks for puzzle logic and data loading
– utils/, constants.ts, types.ts
- config: tsconfig.*.json, eslint.config.js, vite.config.ts

##### README Highlights
- Tech stack: React, TypeScript, Vite, react-chessboard, chess.js
- Features implemented: puzzle loading, move validation, UI feedback, playlists (localStorage mock), mobile responsiveness
- Future: rating filters, spaced repetition, analytics, backend server

##### Key Components
a. UI Layer
- Pages (Home, Login, Puzzle Explorer, Playlists, Profile, Settings, Stats)
- Reusable Components (ChessBoard, InfoCard, Sidebar, Footer, LoadingStates)
b. State & Data Layer
- SessionContext (auth state via localStorage)
- Custom Hooks (useChessPuzzle, usePlaylists, usePuzzleLoader, usePuzzleNavigation)
c. Data Source
- Static JSON puzzles in public/ (by rating)
- Future: REST API to backend database (Lichess import)
d. External Libraries & Services
- react-chessboard (visual board)
- chess.js (move validation & FEN parsing)
- localStorage (user session & playlists mock)
- Lichess puzzle database (external CC0 data source)

##### Interactions & Data Flows
- User navigates to a Page → Page loads data via Hooks → Hooks call API functions → fetch() reads public JSON (or backend endpoint) → data flows back to Hooks → Context/Hooks update component state → Components render UI / respond to user moves → move events validated by chess.js → state updates → UI refresh
- Playlist actions: UI → usePlaylists Hook → localStorage reads/writes → UI updates
- Authentication: LoginPage → SessionContext → localStorage → context provider → pages/components consume auth state

##### Architectural Patterns & Principles
- Component-based UI (React)
- Separation of concerns:
- Presentation (components) vs. Data fetching & state (hooks & context)
- Future layering: thin frontend (React) → API layer (Node/Express or similar) → Database (PostgreSQL or Mongo)

##### Essential Elements to Capture
- Frontend layers (Pages, Components, Hooks, Context)
- Data flow from UI to puzzle store (public JSON) and back
- Validation path through chess.js/react-chessboard
- Mock auth via localStorage and SessionContext
- Placeholder for future backend/API & database

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Containers
    subgraph "Frontend"
        subgraph "UI Layer"
            HP["HomePage"]:::ui
            LP["LoginPage"]:::ui
            RP["RegisterPage"]:::ui
            EXP["PuzzleExplorerPage"]:::ui
            PlP["PlaylistsPage"]:::ui
            PrP["ProfilePage"]:::ui
            SP["SettingsPage"]:::ui
            STP["StatsPage"]:::ui
        end

        subgraph "Components"
            CB["ChessBoard"]:::ui
            IC["InfoCard"]:::ui
            SB["Sidebar"]:::ui
            FT["Footer"]:::ui
            LS["LoadingStates"]:::ui
            PV["PlaylistViewer"]:::ui
            PG["PlaylistGrid"]:::ui
            PEC["PuzzleExplorerContent"]:::ui
            TC["TrainingContent"]:::ui
            TI["TrainingInfo"]:::ui
            TM["TrainingMode"]:::ui
            RA["RequireAuth"]:::ui
        end

        subgraph "State & Data Layer"
            SC["SessionContext"]:::state
            UCP["useChessPuzzle Hook"]:::state
            UP["usePlaylists Hook"]:::state
            UPL["usePuzzleLoader Hook"]:::state
            UPN["usePuzzleNavigation Hook"]:::state
        end

        subgraph "API Layer"
            FP["fetchPuzzles API"]:::api
            FPP["fetchPlaylistPuzzles API"]:::api
            Backend["Backend API Service"]:::external
        end
    end

    subgraph "Data Sources"
        JSON["Static JSON Puzzle Store"]:::data
        LSDB["localStorage"]:::data
        DB["Future Database"]:::data
    end

    subgraph "External Libraries & Services"
        RC["react-chessboard"]:::external
        CJ["chess.js"]:::external
        Lichess["Lichess Puzzle Database"]:::external
    end

    %% Data Flows
    HP -->|"invokes"| UPL
    LP -->|"invokes"| SC
    RP -->|"invokes"| SC
    EXP -->|"invokes"| UPL
    PlP -->|"invokes"| UP
    PrP -->|"invokes"| SC
    SP -->|"invokes"| SC
    STP -->|"invokes"| UPL

    CB -->|"renders board"| RC
    CB -->|"validates moves"| CJ

    UCP -->|"uses context"| SC
    UP -->|"reads/writes"| LSDB
    SC -->|"persists auth"| LSDB

    UPL -->|"calls"| FP
    UPL -->|"calls"| FPP
    UPN -->|"calls"| FP

    FP -->|"fetches from"| JSON
    FPP -->|"fetches from"| JSON
    FP -->|"future fetch from"| Backend
    FPP -->|"future fetch from"| Backend
    Backend -->|"queries"| DB

    Lichess -->|"external source"| JSON

    %% Click Events - Pages
    click HP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/HomePage.tsx"
    click LP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/LoginPage.tsx"
    click RP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/RegisterPage.tsx"
    click EXP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/PuzzleExplorerPage.tsx"
    click PlP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/PlaylistsPage.tsx"
    click PrP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/ProfilePage.tsx"
    click SP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/SettingsPage.tsx"
    click STP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/pages/StatsPage.tsx"

    %% Click Events - Components
    click CB "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/ChessBoard.tsx"
    click IC "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/InfoCard.tsx"
    click SB "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/Sidebar.tsx"
    click FT "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/Footer.tsx"
    click LS "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/LoadingStates.tsx"
    click PV "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/PlaylistViewer.tsx"
    click PG "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/PlaylistGrid.tsx"
    click PEC "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/PuzzleExplorerContent.tsx"
    click TC "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/TrainingContent.tsx"
    click TI "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/TrainingInfo.tsx"
    click TM "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/TrainingMode.tsx"
    click RA "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/components/RequireAuth.tsx"

    %% Click Events - State & Data Layer
    click SC "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/context/SessionContext.tsx"
    click UCP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/hooks/useChessPuzzle.ts"
    click UP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/hooks/usePlaylists.ts"
    click UPL "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/hooks/usePuzzleLoader.ts"
    click UPN "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/hooks/usePuzzleNavigation.ts"

    %% Click Events - API Layer
    click FP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/api/fetchPuzzles.ts"
    click FPP "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/api/fetchPlaylistPuzzles.ts"

    %% Click Events - Data Sources
    click JSON "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/public/puzzles_samples.json"

    %% Click Events - Utilities & Config (optional)
    click Main "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/main.tsx"
    click App "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/src/App.tsx"
    click ViteCfg "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/vite.config.ts"
    click TS1 "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/tsconfig.json"
    click TS2 "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/tsconfig.app.json"
    click TS3 "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/tsconfig.node.json"
    click ESL "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/eslint.config.js"
    click HTML "https://github.com/jairejustin/woodpecker-chess/blob/main/frontend/index.html"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef state fill:#90EE90,stroke:#333,stroke-width:1px
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#FFB347,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
