b3ni/quasar

Fork 0

Files

Benito Rodríguez b92cc19137

CI / lint (push) Failing after 7s

Details

CI / test-backend (push) Has been skipped

Details

CI / test-frontend (push) Has been skipped

Details

CI / test-e2e (push) Has been skipped

Details

Refactor code structure for improved readability and maintainability

2026-02-23 19:08:57 +01:00

9.6 KiB

Raw Blame History

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
🎨 Landing Page Inmersiva — Mass Effect-inspired UI con glassmorphism y efectos holográficos
✅ Web Interface Guidelines — 95% compliance con accesibilidad y semántica HTML5
📱 Mobile-First Responsive — Diseño adaptable a todos los tamaños de pantalla
<EFBFBD>️ 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/02-tecnico/apis.md](docs/02-tecnico/apis.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 (Next.js)
cd frontend && yarn dev

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

Usage

Create Platform — Go to /games, add Nintendo, PlayStation, etc.
Create Game — Add game manually or import from ROMs
Scan ROMs — Go to /roms, scan directory with ROM files
Link Metadata — Search game on IGDB/RAWG, link to ROM
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/          # Next.js 16 + Shadcn UI + Tailwind CSS
│  ├── src/
│  │  ├── app/
│  │  │  ├── layout.tsx           # Root layout con metadata SEO
│  │  │  ├── page.tsx             # Landing page con componentes
│  │  │  └── globals.css          # Tema Mass Effect + animaciones
│  │  ├── components/
│  │  │  ├── landing/
│  │  │  │  ├── Navbar.tsx        # Navbar con glassmorphism
│  │  │  │  ├── Hero.tsx         # Hero section con featured game
│  │  │  │  ├── GameGrid.tsx     # Grid de tarjetas con hover effects
│  │  │  │  └── Footer.tsx       # Footer minimalista
│  │  │  └── ui/                 # Componentes Shadcn UI
│  │  └── lib/
│  │     └── utils.ts            # Utilidades de Shadcn UI
│
├── tests/
│  ├── e2e/           # Playwright E2E tests (15 tests)
│  └── *.spec.ts      # Config validation tests
│
├── docs/             # Documentation
│  ├── README.md      # Documentation index
│  ├── 01-conceptos/  # Fundamental concepts and requirements
│  ├── 02-tecnico/   # Technical documentation
│  ├── 03-analisis/  # Comparative analysis
│  └── 04-operaciones/ # Operations and deployment
│
├── .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/02-tecnico/apis.md](docs/02-tecnico/apis.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/02-tecnico/apis.md.

Testing

General Tests

# 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

Frontend Development and Testing

# Navigate to frontend directory
cd frontend

# Install dependencies
yarn install

# Start development server
yarn dev
# Frontend will be available at: http://localhost:5173

# Build for production
yarn build

# Preview production build
yarn preview

# Run frontend-specific tests
yarn test

# Run frontend tests with coverage
yarn test:coverage

# Lint frontend code
yarn lint

# Format frontend code
yarn format

# Type check frontend
yarn type-check

Backend Development and Testing

# Navigate to backend directory
cd backend

# Install dependencies
yarn install

# Start development server
yarn dev
# Backend API will be available at: http://localhost:3000

# Run backend tests
yarn test

# Run backend tests with coverage
yarn test:coverage

# Run specific test file
yarn test -- gamesController.spec.ts

# Run tests in watch mode
yarn test:watch

# Lint backend code
yarn lint

# Format backend code
yarn format

# Type check backend
yarn type-check

# Database operations
yarn prisma:migrate
yarn prisma:generate
yarn prisma:studio

API Testing

# Test backend API endpoints
curl http://localhost:3000/health

# Test games endpoint
curl http://localhost:3000/api/games

# Test metadata search
curl "http://localhost:3000/api/metadata/search?q=Mario"

# Test ROM scanning
curl -X POST http://localhost:3000/api/roms/scan -d '{"path":"/path/to/roms"}'

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/02-tecnico/apis.md](docs/02-tecnico/apis.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/01-conceptos/architecture.md.

Tech Stack

Backend: Node.js, Fastify, Prisma ORM, SQLite, TypeScript
Frontend: Next.js 16, React 19, TypeScript, Shadcn UI, Tailwind CSS 4
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/README.md — Documentation index and navigation guide
docs/01-conceptos/requirements.md — Project requirements and use cases
docs/01-conceptos/architecture.md — System architecture and design decisions
docs/01-conceptos/data-model.md — Database schema and entities
docs/02-tecnico/apis.md — APIs configuration and integration guide
docs/02-tecnico/frontend.md — Complete frontend architecture and implementation
docs/03-analisis/competitive-analysis.md — Market analysis and competitive research

Development

Adding a new feature

Create test file: tests/feature.spec.ts (TDD)
Write failing test
Implement feature
Run tests: yarn test
Run lint: yarn lint
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:

Run yarn test before pushing
Run yarn format to auto-format code
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) — Landing page completa con estética Mass Effect-inspired Last updated: 2026-02-23 Test coverage: 122+ unit tests + 15 E2E tests ✅ Documentation: Frontend landing page documentado ✅

9.6 KiB Raw Blame History Unescape Escape

Quasar 🎮

Features

Quick Start

Prerequisites

Installation

Usage

Project Structure

Configuration

Environment Variables

Testing

General Tests

Frontend Development and Testing

Backend Development and Testing

API Testing

Troubleshooting

Backend won't start

Tests failing with "DATABASE_URL not found"

Metadata search returns no results

Frontend can't reach backend

Architecture

Tech Stack

Security

Documentation

Development

Adding a new feature

Running Gitea Actions locally

Contributing

License

Support

9.6 KiB

Raw Blame History