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:

Compares filesystem ROMs with database entries to avoid re-indexing
Authenticates with IGDB via Twitch OAuth using client credentials
Scrapes metadata for new games only with rate limiting (4 concurrent requests)
Stores normalized data in SQLite with proper foreign key relationships
Handles duplicate games and metadata updates gracefully

Web Interface:

FastAPI serves modern responsive web interface with Tailwind CSS
JWT-based authentication with three user roles: demo, normal, super
Demo users can browse but not download; normal users get full access; super users can manage everything
Pagination, favorites system, and file downloads for authorized users
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

db-init           # Initialize database with current schema
migrate stamp     # Mark database as up-to-date with migrations

Migration Management

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

Modify models in src/libs/database.py
Create migration: migrate create "description of changes"
Review generated migration file in migrations/versions/
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.

4.4 KiB Raw Blame History