100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development Commands
|
|
|
|
The project uses devenv.nix for development environment management. All commands should be run from the repository root:
|
|
|
|
- `tests` - Run pytest with coverage
|
|
- `lint` - Check code with ruff and black
|
|
- `fix` - Auto-fix code issues with ruff and black
|
|
- `typecheck` - Run pyright type checking
|
|
- `run` - Execute the main ROM scraper application
|
|
- `serve` - Start the FastAPI web server
|
|
- `create-admin` - Create initial admin user for web interface
|
|
- `migrate` - Database migration management (see Migration Commands)
|
|
- `db-init` - Initialize database schema (first-time setup)
|
|
- `db-upgrade` - Apply pending database migrations
|
|
- `db-create` - Create new migration (requires message argument)
|
|
- `build` - Build the application using build.sh (creates zipapp in release/)
|
|
|
|
## Architecture
|
|
|
|
This is a Python ROM metadata scraper and web-based ROM management system for DOS games:
|
|
|
|
### Core Components
|
|
|
|
- **Main Application** (`src/__main__.py`): Async scraper that scans ROM directories, fetches metadata from IGDB API, and stores everything in SQLite
|
|
- **Web Application** (`src/webapp.py`): FastAPI server with user authentication, ROM browsing, downloads, and admin interface
|
|
- **Configuration** (`src/libs/config.py`): XDG-compliant config management with automatic setup prompts
|
|
- **Database Layer** (`src/libs/database.py`): SQLAlchemy models with many-to-many relationships for games, metadata, genres, tags, and users
|
|
- **Authentication** (`src/libs/auth.py`): JWT-based auth with bcrypt password hashing and role-based access control
|
|
- **Data Models** (`src/libs/objects.py`): Dataclasses for Game, Metadata, and Roms collections
|
|
- **API Integration** (`src/libs/apis.py`): IGDB API client with Twitch OAuth authentication
|
|
- **Utilities** (`src/libs/functions.py`): Title cleaning and year extraction from ROM filenames
|
|
|
|
### Data Flow
|
|
|
|
**ROM Scraping:**
|
|
1. Compares filesystem ROMs with database entries to avoid re-indexing
|
|
2. Authenticates with IGDB via Twitch OAuth using client credentials
|
|
3. Scrapes metadata for new games only with rate limiting (4 concurrent requests)
|
|
4. Stores normalized data in SQLite with proper foreign key relationships
|
|
5. Handles duplicate games and metadata updates gracefully
|
|
|
|
**Web Interface:**
|
|
1. FastAPI serves modern responsive web interface with Tailwind CSS
|
|
2. JWT-based authentication with three user roles: demo, normal, super
|
|
3. Demo users can browse but not download; normal users get full access; super users can manage everything
|
|
4. Pagination, favorites system, and file downloads for authorized users
|
|
5. Admin interface for user management and metadata editing
|
|
|
|
### Key Technical Details
|
|
|
|
- Uses asyncio with semaphore-based rate limiting for API requests
|
|
- SQLAlchemy with declarative base and proper naming conventions
|
|
- FastAPI with Jinja2 templates, JWT authentication, and role-based access control
|
|
- Configuration supports both environment variables and .env files
|
|
- Custom PathType for storing pathlib.Path objects in database
|
|
- Batch processing for database operations with configurable batch sizes
|
|
- Modern responsive UI with Tailwind CSS and Alpine.js for interactivity
|
|
|
|
## Database Migrations
|
|
|
|
The project uses Alembic for database schema versioning and migrations:
|
|
|
|
### First-Time Setup
|
|
```bash
|
|
db-init # Initialize database with current schema
|
|
migrate stamp # Mark database as up-to-date with migrations
|
|
```
|
|
|
|
### Migration Management
|
|
```bash
|
|
migrate create "description" # Create new migration file
|
|
migrate upgrade # Apply all pending migrations
|
|
migrate current # Show current database revision
|
|
migrate history # Show migration history
|
|
migrate check # Check database migration status
|
|
```
|
|
|
|
### Schema Changes
|
|
1. Modify models in `src/libs/database.py`
|
|
2. Create migration: `migrate create "description of changes"`
|
|
3. Review generated migration file in `migrations/versions/`
|
|
4. Apply migration: `migrate upgrade`
|
|
|
|
### Migration Files
|
|
- Located in `migrations/versions/`
|
|
- Named with revision ID and description
|
|
- Contain `upgrade()` and `downgrade()` functions
|
|
- Support batch operations for SQLite compatibility
|
|
|
|
## Environment Setup
|
|
|
|
Requires IGDB API credentials:
|
|
- `IGDB_CLIENT_ID` - Twitch client ID
|
|
- `IGDB_SECRET_KEY` - Twitch client secret
|
|
|
|
Can be provided via environment variables or `.env` file in project root. |