🎮 DosVault

Your Personal DOS Game Collection Manager

DosVault is a modern, web-based collection manager for DOS games that combines powerful metadata scraping with an intuitive browsing experience. Built with Python and FastAPI, it helps you organize, discover, and manage your retro gaming library with style.

✨ Features

🎯 Core Functionality

• Automatic Metadata Scraping - Pulls game information, cover art, and screenshots from IGDB API
• Local Image Storage - Downloads and caches all images locally for fast loading
• Intelligent ROM Detection - Scans directories and avoids re-indexing existing games
• Advanced Search & Filtering - Find games by title, genre, developer, or description
• Genre & Tag Browsing - Organized categorization with alphabetical sorting

🌐 Modern Web Interface

• Responsive Design - Works beautifully on desktop, tablet, and mobile
• Multiple View Modes - Switch between grid and list views
• Interactive Screenshots - Click to view full-screen image galleries
• Smart Pagination - Navigate large collections with ease
• Real-time Favorites - Heart games to build your personal collection

🔐 User Management

• Role-Based Access Control - Demo, Normal, and Super Admin roles
• Secure Authentication - JWT-based auth with bcrypt password hashing
• Personal Favorites - Each user maintains their own favorites list
• Admin Dashboard - User management and system overview

📱 Mobile-First

• Hamburger Navigation - Clean mobile menu system
• Touch-Optimized - Large buttons and smooth interactions
• Responsive Controls - Pagination and filters work great on mobile

🚀 Quick Start

Prerequisites

• Python 3.11+
• Devenv (recommended) or manual dependency management
• IGDB API credentials (free from Twitch Developer Console)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd dosfrontend
   

2. Set up environment:

   # With devenv (recommended)
   devenv shell
   
   # Or manually install dependencies
   pip install fastapi uvicorn sqlalchemy alembic bcrypt python-jose aiohttp
   

3. Configure IGDB API: Create a .env file with your IGDB credentials:

   IGDB_CLIENT_ID=your_twitch_client_id
   IGDB_SECRET_KEY=your_twitch_client_secret
   

4. Initialize database:

   db-init
   create-admin  # Create your first admin user
   

5. Run the application:

   serve  # Starts web server
   run    # Runs ROM scraper (optional)
   

6. Access DosVault: Open http://localhost:8080 in your browser

📁 Project Structure

dosfrontend/
├── src/
│   ├── __main__.py          # ROM scraper application
│   ├── webapp.py            # FastAPI web server
│   └── libs/
│       ├── config.py        # XDG-compliant configuration
│       ├── database.py      # SQLAlchemy models
│       ├── auth.py          # JWT authentication
│       ├── apis.py          # IGDB API integration
│       └── functions.py     # Utility functions
├── templates/               # Jinja2 HTML templates
├── migrations/             # Database schema versions
├── devenv.nix             # Development environment
└── CLAUDE.md              # Development guidance

🎮 Usage

Scraping ROMs

# Scan ROM directories and fetch metadata
run

Web Interface

# Start the web server
serve

Database Management

# Create migrations
migrate create "description of changes"

# Apply migrations  
migrate upgrade

# Check migration status
migrate current

Administration

# Create admin user
create-admin

# Run tests
tests

# Code quality
lint
typecheck

⚙️ Configuration

DosVault uses XDG-compliant configuration stored in:

• Linux/Mac: ~/.config/dosfrontend/
• Windows: %APPDATA%/dosfrontend/

Key configuration options:

• ROM directories to scan
• Image storage location
• Database path
• Web server host/port
• IGDB API credentials

🏗️ Architecture

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy - Database ORM with proper relationships
• Alembic - Database migration management
• AsyncIO - Concurrent API requests with rate limiting
• JWT + BCrypt - Secure authentication

Frontend

• Jinja2 - Server-side templating
• Tailwind CSS - Utility-first styling
• Alpine.js - Lightweight JavaScript framework
• Responsive Design - Mobile-first approach

Data Flow

1. Scraper scans ROM directories and compares with database
2. IGDB API provides metadata via Twitch OAuth
3. Images are downloaded and cached locally
4. Web interface serves games with fast local assets
5. Users browse, search, and manage favorites

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (tests, lint)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• IGDB for providing comprehensive game metadata
• Twitch for OAuth authentication to IGDB API
• FastAPI for the excellent modern Python web framework
• Tailwind CSS for making responsive design a breeze
• DOSBox community for keeping retro gaming alive

---

Built with ❤️ for retro gaming enthusiasts