002ed92bea
This commit implements iOS/Android mobile app support using Capacitor and adds a comprehensive opening training feature with LLM-powered explanations. ## Mobile App Infrastructure - Add Capacitor configuration for iOS/Android builds - Create mobile build script that excludes API routes - Update Next.js config for conditional static export - Add layout components with generateStaticParams for static builds - Generate 500+ static pages for offline mobile use ## Chess Engine Abstraction - Create ChessEngine interface for pluggable implementations - Add LocalEngine (GPL - uses stockfish.js in browser) - Add RemoteEngine (proprietary - calls API server) - Factory pattern selects engine based on environment - Enables GPL compliance for web, proprietary for mobile ## Opening Training Feature - Interactive opening repertoire training - Move validation with engine-backed feedback - LLM explanations using Gemini API - Wikipedia integration for opening context - Opening family grouping (e4, d4, c4, etc.) - Session state management - Real-time move feedback with evaluation Components: - OpeningSelector: Browse and select openings by family - OpeningTrainer: Main training interface with chessboard - MoveFeedback: Display move quality and LLM explanations - WikipediaSummary: Show opening history and context - ErrorBoundary: Graceful error handling Services: - openingLoader: Load and filter opening database - engineService: Engine evaluation wrapper - moveValidator: Validate moves against repertoire - feedbackGenerator: Generate contextual feedback - wikipediaService: Fetch and cache Wikipedia data - sessionManager: Track training session state ## Wikipedia Integration - Automatic Wikipedia article fetching for openings - Client-side and server-side caching - Sanitized summaries with proper formatting - Link opening database to Wikipedia slugs - API endpoints for on-demand fetching ## Docker Improvements - Add entrypoint script for automatic data setup - Fetch Wikipedia data on first container startup - Generate opening move index automatically - Remove generated data from git (public/openings/*.json, public/wikipedia/*.json) - Add READMEs explaining data requirements - Update .gitignore for generated files ## Dual Licensing Strategy - Add LICENSING.md explaining dual licensing approach - GPL-3.0 for web builds (includes Stockfish) - Proprietary option for mobile builds (no GPL code) - Single codebase, multiple licensing models - Legal compliance documented ## API Endpoints - POST /api/v1/llm/opening-explanation - Get LLM move explanations - GET /api/v1/wikipedia/summary - Fetch Wikipedia summaries ## Type Updates - Add openingTraining types - Update Tutor component to use ChessEngine interface - Add Gemini error handling types 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
3.9 KiB
3.9 KiB
Licensing Strategy
Overview
This project uses a dual licensing approach based on how the software is built and distributed:
GPL-3.0 License (Web Version)
The web version of Chess Tutor includes Stockfish.js, which is licensed under GPL-3.0. Therefore:
- Source code: GPL-3.0
- Web builds (using
LocalEngine): GPL-3.0 - Any distribution that includes Stockfish.js: GPL-3.0
Users can:
- Use the web version for free
- Bring their own API keys (Gemini)
- Run locally with client-side Stockfish
Proprietary License (Mobile Version)
The mobile version (iOS/Android) does NOT bundle Stockfish.js. Instead, it uses:
RemoteEngine- Makes API calls to a hosted server for chess analysis- No GPL code is included in the mobile build
- Static export with API-only architecture
Therefore, the mobile app can be distributed under a proprietary license:
- Sold on App Store / Google Play
- Uses hosted API service
- No GPL restrictions apply
How This Works
Code Architecture
// Engine abstraction allows swapping implementations
export interface ChessEngine {
evaluate(fen: string, depth?: number): Promise<EngineEvaluation>;
terminate(): void;
}
// GPL-licensed (web only)
class LocalEngine implements ChessEngine {
// Uses stockfish.js in browser
}
// No GPL dependencies (mobile)
class RemoteEngine implements ChessEngine {
// Calls API server
}
Build Configuration
Web Build (npm run build):
- Output:
output: 'standalone'(Next.js server) - Includes: API routes with Stockfish
- Engine:
LocalEngine(GPL) - License: GPL-3.0
Mobile Build (npm run build:mobile):
- Output:
output: 'export'(static HTML/JS) - Excludes: API routes (temporarily removed during build)
- Engine:
RemoteEngine(proprietary) - License: Proprietary
Legal Compliance
GPL Compliance (Web)
The web version complies with GPL-3.0:
- ✅ Source code is available
- ✅ GPL license is included
- ✅ Users can modify and redistribute
- ✅ Users bring their own API keys (no lock-in)
Mobile Compliance
The mobile version is NOT a derivative work of GPL code:
- ✅ No Stockfish.js included in build
- ✅ Uses network API calls (not linking)
- ✅ Can be licensed separately
- ✅ Users pay for hosted service
File Structure
chess_tutor/
├── LICENSE # GPL-3.0 (for source code and web)
├── LICENSING.md # This file (dual licensing explanation)
├── src/
│ └── lib/
│ ├── stockfish.ts # GPL-licensed (web only)
│ └── engine/
│ ├── LocalEngine.ts # GPL-licensed (web only)
│ └── RemoteEngine.ts # Proprietary (mobile)
├── public/ # Generated data (not in git)
│ ├── openings/*.json # Fetched at Docker startup
│ └── wikipedia/*.json # Fetched at Docker startup
└── scripts/
├── docker-entrypoint.sh # Fetches data on startup
└── build-mobile.sh # Excludes GPL code
Developer Guidelines
Contributing
All contributions to the source code repository are subject to GPL-3.0.
Building for Web
npm run build
npm start
# GPL-3.0 applies
Building for Mobile
npm run build:mobile
# Proprietary license can apply (no GPL code included)
Deploying
Web Deployment:
- Must comply with GPL-3.0
- Must provide source code
- Can be self-hosted for free
Mobile App Store:
- Uses proprietary license
- Connects to hosted API
- Paid app model allowed
Questions?
- Web version: GPL-3.0 applies because Stockfish.js is included
- Mobile version: Proprietary license allowed because no GPL code is bundled
- Source code: GPL-3.0 (contains GPL integration code)
This approach allows:
- ✅ Free web version (GPL-compliant)
- ✅ Paid mobile app (proprietary)
- ✅ Single codebase
- ✅ Legal compliance