Spaces:
Running
Running
Delete CLAUDE.md
Browse files
CLAUDE.md
DELETED
@@ -1,68 +0,0 @@
|
|
1 |
-
# CLAUDE.md
|
2 |
-
|
3 |
-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
4 |
-
|
5 |
-
## Development Commands
|
6 |
-
|
7 |
-
### Local Development
|
8 |
-
- `make dev` - Start local Python HTTP server on port 8000
|
9 |
-
- `make dev-python` - Start FastAPI server on port 7860 (production-like)
|
10 |
-
- `npm run dev` - Alternative Python HTTP server command
|
11 |
-
- `python local-server.py 8000` - Direct local server command
|
12 |
-
|
13 |
-
### Docker Development
|
14 |
-
- `make docker-dev` - Start with docker-compose (recommended for production testing)
|
15 |
-
- `make docker-build` - Build Docker image
|
16 |
-
- `make docker-run` - Run container with environment variables
|
17 |
-
- `make logs` - View Docker logs
|
18 |
-
- `make stop` - Stop Docker containers
|
19 |
-
|
20 |
-
### Utilities
|
21 |
-
- `make install` - Install both Python and Node.js dependencies
|
22 |
-
- `make clean` - Remove temporary files and dependencies
|
23 |
-
- `make help` - Show all available commands
|
24 |
-
|
25 |
-
## Architecture Overview
|
26 |
-
|
27 |
-
### Frontend Structure
|
28 |
-
This is a **vanilla JavaScript modular application** with no build step. Key architectural patterns:
|
29 |
-
|
30 |
-
**Module Organization:**
|
31 |
-
- `app.js` - Main application controller, handles UI state and round management
|
32 |
-
- `clozeGameEngine.js` - Core game logic, word selection, and scoring
|
33 |
-
- `bookDataService.js` - Manages book data fetching from Hugging Face Datasets API
|
34 |
-
- `aiService.js` - OpenRouter API integration for AI-powered word selection and contextualization
|
35 |
-
- `chatInterface.js` - Modal-based chat UI for contextual hints
|
36 |
-
- `conversationManager.js` - AI conversation state management for chat functionality
|
37 |
-
- `welcomeOverlay.js` - First-time user onboarding
|
38 |
-
|
39 |
-
**Key Architectural Decisions:**
|
40 |
-
- **No capitalized words as blanks** - All word selection logic filters out capitalized words (proper nouns, sentence starters)
|
41 |
-
- **Progressive difficulty** - Levels 1-2: 1 blank, 3-4: 2 blanks, 5+: 3 blanks
|
42 |
-
- **Batch API processing** - Processes both passages simultaneously to avoid rate limits, with fallback to sequential processing
|
43 |
-
- **Accessible fonts** - Uses system font stack throughout UI, avoiding decorative fonts for accessibility
|
44 |
-
|
45 |
-
### Backend Structure
|
46 |
-
**Dual server setup:**
|
47 |
-
- `app.py` - FastAPI server for production (HuggingFace Spaces), handles environment variable injection
|
48 |
-
- `local-server.py` - Simple HTTP server for local development
|
49 |
-
|
50 |
-
**Environment variable handling:**
|
51 |
-
- Production: FastAPI injects API keys via meta tags, read by `init-env.js`
|
52 |
-
- Local: Environment variables accessed directly via `process.env` or `window`
|
53 |
-
|
54 |
-
### Data Flow
|
55 |
-
1. **Game Initialization**: BookDataService fetches book metadata from HuggingFace
|
56 |
-
2. **Passage Processing**: AIService processes passages via OpenRouter API for word selection and contextualization
|
57 |
-
3. **Word Selection**: Multi-layered selection (AI → manual fallback → emergency fallback) with capitalization filtering
|
58 |
-
4. **Chat System**: Context-aware conversation manager tracks per-blank question state
|
59 |
-
|
60 |
-
### API Dependencies
|
61 |
-
- **OpenRouter API** - AI word selection, contextualization, and chat responses (Google Gemma 3)
|
62 |
-
- **HuggingFace Datasets API** - Book content and metadata retrieval
|
63 |
-
- **External**: CDN-hosted Tailwind CSS and Google Fonts
|
64 |
-
|
65 |
-
### Styling Architecture
|
66 |
-
- **CSS Custom Properties** - Consistent theming with `--aged-paper`, `--typewriter-ink` variables
|
67 |
-
- **Accessible Design** - System fonts, proper contrast, keyboard navigation
|
68 |
-
- **Responsive Layout** - Mobile-first design with progressive enhancement
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|