How jairejustin/woodpecker-chess works
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