Quasar 🎮

A self-hosted video game library manager. Scan ROM files, enrich metadata from multiple APIs (IGDB, RAWG, TheGamesDB), and manage your personal game collection.

Features

• 📁 ROM Scanning — Scan directories for ROM files (ZIP, 7z, RAR)
• 🔍 Metadata Enrichment — Fetch game info, artwork, ratings from 3+ APIs
• 🎯 Game Library — Create, edit, and organize games by platform
• 🎨 Multi-API Support — IGDB (Twitch OAuth), RAWG, TheGamesDB
• 🛡️ Privacy First — All data stored locally, no cloud sync
• 🔐 Secure — API keys via environment variables, never committed

Quick Start

Prerequisites

• Node.js 18+
• Yarn 4.x (package manager)

Installation

# 1. Clone repository
git clone https://your-gitea-instance/your-org/quasar.git
cd quasar

# 2. Install dependencies
yarn install

# 3. Setup environment
cp .env.example .env.local

# 4. Get API keys (optional, but recommended)
# See: docs/API_KEYS.md

# 5. Run migrations
cd backend
npm run prisma:migrate
cd ..

# 6. Start development servers
# Terminal 1: Backend
cd backend && yarn dev

# Terminal 2: Frontend
cd frontend && yarn dev

# 7. Open browser
# Frontend: http://localhost:5173
# Backend API: http://localhost:3000

Usage

1. Create Platform — Go to /games, add Nintendo, PlayStation, etc.
2. Create Game — Add game manually or import from ROMs
3. Scan ROMs — Go to /roms, scan directory with ROM files
4. Link Metadata — Search game on IGDB/RAWG, link to ROM
5. View Library — See all games with artwork and info

Project Structure

quasar/
├── backend/           # Fastify API + Prisma + SQLite
│  ├── src/
│  │  ├── routes/      # REST endpoints (/games, /roms, /metadata, etc.)
│  │  ├── services/    # Business logic (metadata clients, romscanning, etc.)
│  │  └── controllers/ # Request handlers
│  └── tests/          # Vitest unit tests (63+ tests)
│
├── frontend/          # React + Vite + React Query
│  ├── src/
│  │  ├── routes/      # Pages (/games, /roms, etc.)
│  │  ├── components/  # React components (Forms, Dialogs, Cards)
│  │  └── hooks/       # TanStack Query hooks
│  └── tests/          # Vitest + React Testing Library (59+ tests)
│
├── tests/
│  ├── e2e/           # Playwright E2E tests (15 tests)
│  └── *.spec.ts      # Config validation tests
│
├── docs/             # Documentation
│  ├── API_KEYS.md    # How to get API credentials
│  ├── SECURITY.md    # Security guidelines
│  └── ...
│
├── .gitea/
│  └── workflows/
│     └── ci.yml      # Gitea Actions CI pipeline
│
└── .env.example      # Environment template

Configuration

Environment Variables

Copy .env.example to .env.local (or .env.development) and fill in:

# Database (local SQLite)
DATABASE_URL="file:./dev.db"

# API Keys (get from docs/API_KEYS.md)
IGDB_CLIENT_ID=your_client_id
IGDB_CLIENT_SECRET=your_client_secret
RAWG_API_KEY=your_api_key
THEGAMESDB_API_KEY=your_api_key

# App Config
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

For production, use Gitea Secrets. See SECURITY.md and docs/API_KEYS.md.

Testing

# Run all tests (unit + config)
yarn test

# Run backend tests only
cd backend && yarn test

# Run frontend tests only
cd frontend && yarn test:run

# Run E2E tests (requires servers running)
cd backend && yarn dev &
cd frontend && yarn dev &
yarn test:e2e

# Lint & Format
yarn lint
yarn format

Troubleshooting

Backend won't start

Error: EADDRINUSE: address already in use :::3000
→ Kill process on port 3000: lsof -i :3000 | grep LISTEN | awk '{print $2}' | xargs kill -9

Tests failing with "DATABASE_URL not found"

→ Make sure backend/.env exists with DATABASE_URL
→ Or: DATABASE_URL="file:./test.db" yarn test

Metadata search returns no results

→ Check that API keys are correct (docs/API_KEYS.md)
→ Check logs: tail -f backend/logs/*.log
→ Test with: curl http://localhost:3000/api/metadata/search\?q\=Mario

Frontend can't reach backend

→ Make sure backend is running on http://localhost:3000
→ Check frontend/.env has: VITE_API_URL=http://localhost:3000

Architecture

For detailed architecture and decisions, see docs/architecture.md.

Tech Stack

• Backend: Node.js, Fastify, Prisma ORM, SQLite, TypeScript
• Frontend: React 18, Vite, TanStack Query, Tailwind CSS, shadcn/ui
• Testing: Vitest (unit), Playwright (E2E)
• APIs: IGDB (OAuth), RAWG, TheGamesDB

Security

• No data leaves your system — Everything stored locally
• API keys stored securely — Via .env.local or Gitea Secrets
• Input validation — All user input validated with Zod
• CORS configured — Only allows frontend origin

For security guidelines, see SECURITY.md.

Documentation

• SECURITY.md — Security policies and best practices
• docs/API_KEYS.md — How to obtain and configure API credentials
• docs/architecture.md — System architecture and design decisions
• docs/data-model.md — Database schema and entities
• docs/requirements.md — Project requirements and use cases

Development

Adding a new feature

1. Create test file: tests/feature.spec.ts (TDD)
2. Write failing test
3. Implement feature
4. Run tests: yarn test
5. Run lint: yarn lint
6. Commit: git commit -m "feat: add feature description"

Running Gitea Actions locally

# The CI workflow is in .gitea/workflows/ci.yml
# It runs automatically on push/PR to main or develop
# To test locally:

# 1. Lint
yarn lint

# 2. Backend tests
cd backend && yarn test

# 3. Frontend tests
cd frontend && yarn test:run

# 4. E2E tests (requires servers running)
cd backend && yarn dev &
cd frontend && yarn dev &
yarn test:e2e

Contributing

Pull requests welcome. Please:

1. Run yarn test before pushing
2. Run yarn format to auto-format code
3. Add tests for new features

License

MIT (or choose your license)

Support

• Docs: See /docs folder
• Issues: Report bugs on this repo
• Discussions: Use repo discussions for questions

---

Status: MVP (v1.0.0) — Ready for self-hosted deployment.
Last updated: 2026-02-12
Test coverage: 122+ unit tests + 15 E2E tests ✅