b3ni/quasar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add frontend README and backend test database

Browse Source 
- Create frontend/README.md with setup, testing, and API integration instructions
- Add backend test database file for local testing
- Implement README validation tests to ensure documentation completeness
- Update project documentation to reflect new structure and features
This commit is contained in:
Benito Rodríguez
2026-02-12 20:53:59 +01:00
parent ce54db38d9
commit c27e9bec7a
5 changed files with 578 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
README.md
View File

@@ -1,80 +1,256 @@
# Quasar
# Quasar 🎮
## Descripción
A self-hosted video game library manager. Scan ROM files, enrich metadata from multiple APIs (IGDB, RAWG, TheGamesDB), and manage your personal game collection.
Quasar es una aplicación web para al gestión de una biblioteca personal de videjuegos. Permite a los usuarios catalogar, organizar y buscar sus juegos de manera eficiente. Se pueden agregar videjuegos físicos, digitales y roms de emuladores.
## Features
## Características
- 📁 **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
- **Catálogo de Videjuegos**: Permite agregar, editar y eliminar juegos de la biblioteca.
- **Organización**: Clasificación por género, plataforma, estado (completado, en progreso, pendiente) y calificación personal.
- **Búsqueda Avanzada**: Filtros para encontrar juegos rápidamente según diferentes criterios.
- **Búsqueda de Metadatos**: Integración con APIs externas para obtener información adicional sobre los juegos.
## Quick Start
## Seguridad
### Prerequisites
Para información sobre políticas de seguridad, vulnerabilidades y prácticas recomendadas, consulta [SECURITY.md](SECURITY.md).
- **Node.js 18+**
- **Yarn 4.x** (package manager)
## Configuración de APIs
Quasar se integra con múltiples servicios de metadatos: IGDB, RAWG y TheGamesDB. Para obtener credenciales y configurar estas APIs, consulta [docs/API_KEYS.md](docs/API_KEYS.md).
### Variables de Entorno
La aplicación requiere variables de entorno sensibles (como claves de API y credenciales de base de datos).
Usa `.env.local` o `.env.{NODE_ENV}.local` para desarrollo. **Nunca** hagas commit de archivos `.env` al repositorio:
### Installation
```bash
# 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
# Edita .env.local con tus credenciales
# 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
```
## Otros proyectos relacionados, para coger ideas y funcionalidades
## Usage
| Herramienta | Categoría | Descripción | Features Destacadas | Ideal Para | Enlace Oficial |
| ------------------------ | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| RomM | Gestor de ROMs y Metadatos | Gestor self-hosted de ROMs con interfaz web moderna. | Escanea, enriquece y navega por colecciones de juegos. Obtiene metadatos de IGDB, Screenscraper y MobyGames. Descarga automática de carátulas y fanarts. | Gestionar colecciones de ROMs y videojuegos retro/modernos con metadatos y assets visuales. | [GitHub - RomM](https://github.com/rommapp/romm) |
| Gaseous | Gestor de ROMs y Metadatos | Gestor de archivos ROM y metadatos con emulador basado en web. | Gestión de metadatos y archivos ROM. Emulador integrado accesible desde navegador. | Usuarios que buscan una solución todo-en-uno para ROMs y emulación web. | [GitHub - Gaseous](https://github.com/RetroESP32/gaseous) |
| RetroAssembly | Gestor de ROMs y Metadatos | Plataforma para mostrar colecciones de juegos retro en el navegador. | Interfaz web para visualizar y organizar juegos retro. | Coleccionistas de juegos retro que buscan una experiencia visual en el navegador. | [GitHub - RetroAssembly](https://github.com/RetroAssembly/RetroAssembly) |
| Gameyfin | Gestor de Bibliotecas | Gestor de bibliotecas de videojuegos similar a Jellyfin. | Escanea bibliotecas de juegos y presenta los títulos en un navegador web. Organiza juegos de Steam, Epic, GOG y otras fuentes. Interfaz limpia y soporte para plugins. | Gestionar y compartir juegos digitales con amigos o familia. | [GitHub - Gameyfin](https://github.com gameyfin/gameyfin) |
| GameVault | Gestor de Bibliotecas | Plataforma self-hosted para gestionar colecciones de videojuegos. | Integración con IGDB para metadatos y carátulas. Clasificación por edades y personalización de metadatos. Sistema de plugins. | Usuarios que buscan una solución robusta para metadatos y organización de juegos. | [GameVault](https://gamevau.lt/) |
| Retrom | Gestor de Bibliotecas | Servidor de distribución de bibliotecas de juegos retro + frontend/launcher. | Distribución y lanzamiento de juegos retro desde tu propio servidor. Interfaz personalizable. | Colecciones de juegos retro y distribución centralizada. | [GitHub - Retrom](https://github.com/RetroESP32/retrom) |
| Drop | Distribución de Juegos | Plataforma flexible de distribución de juegos. | Permite distribuir y gestionar juegos de forma centralizada. | Distribución de juegos en redes locales o comunidades. | [GitHub - Drop](https://github.com/drop-team/drop) |
| Pterodactyl | Gestión de Servidores | Panel de gestión de servidores de juegos open source. | Permite instalar y gestionar servidores de juegos como Minecraft, CS:GO, etc. Interfaz web moderna y soporte para múltiples usuarios. | Administrar servidores de juegos para comunidades o grupos. | [Pterodactyl](https://pterodactyl.io/) |
| LinuxGSM | Gestión de Servidores | Herramienta de línea de comandos para desplegar servidores de juegos dedicados. | Soporte para más de 100 servidores de juegos. Automatización de instalación y actualización. | Usuarios avanzados que prefieren la línea de comandos. | [LinuxGSM](https://linuxgsm.com/) |
| Lodestone | Gestión de Servidores | Herramienta de hosting open source para Minecraft y otros juegos multijugador. | Gestión simplificada de servidores de Minecraft y otros juegos. | Hosting de servidores de Minecraft y juegos similares. | [GitHub - Lodestone](https://github.com/Lodestone-Team/Lodestone) |
| auto-mcs | Gestión de Servidores | Gestor de servidores de Minecraft multiplataforma. | Automatización de la gestión de servidores de Minecraft. | Usuarios que buscan una solución sencilla para Minecraft. | [GitHub - auto-mcs](https://github.com/auto-mcs/auto-mcs) |
| Pelican Panel | Gestión de Servidores | Panel de control para servidores de juegos. | Interfaz web para gestionar servidores de juegos. | Alternativa a Pterodactyl, con enfoque en simplicidad. | [GitHub - Pelican Panel](https://github.com/pelican-panel/pelican) |
| Sunshine | Streaming y Acceso Remoto | Host de streaming de juegos para Moonlight. | Permite transmitir juegos desde tu PC a otros dispositivos. | Jugar en remoto desde tablets, móviles o TVs. | [GitHub - Sunshine](https://github.com/LizardByte/Sunshine) |
| Games on Whales | Streaming y Acceso Remoto | Plataforma para transmitir escritorios virtuales y juegos mediante Docker. | Streaming de juegos y escritorios virtuales. | Usuarios que buscan una solución de streaming basada en Docker. | [GitHub - Games on Whales](https://github.com/games-on-whales/gow) |
| PlanarAlly | Virtual Tabletop | Mesa de juego virtual con capacidades offline. | Soporte para juegos de rol y tablero. | Jugadores de rol que buscan una mesa virtual self-hosted. | [GitHub - PlanarAlly](https://github.com/PlanarAlly/planarally) |
| Foundry Virtual Tabletop | Virtual Tabletop | Plataforma moderna para juegos de rol. | Herramientas avanzadas para masters y jugadores. | Comunidades de juegos de rol que buscan una solución profesional. | [Foundry Virtual Tabletop](https://foundryvtt.com/) |
| LANCommander | Distribución de Juegos | Plataforma open source para distribución digital de videojuegos. | Permite distribuir juegos en una red local. | Distribución de juegos en LAN o comunidades pequeñas. | [GitHub - LANCommander](https://github.com/LANCommander/LANCommander) |
| Fireshare | Distribución de Juegos | Comparte clips de juegos, videos u otros medios mediante enlaces únicos. | Comparte contenido multimedia de forma sencilla. | Compartir capturas o videos de juegos con amigos. | [GitHub - Fireshare](https://github.com/fireshare/fireshare) |
| Crafty Controller | Herramientas para Minecraft | Panel de control y lanzador para servidores de Minecraft. | Gestión simplificada de servidores de Minecraft. | Administrar servidores de Minecraft de forma visual. | [GitHub - Crafty Controller](https://github.com/crafty-controller/crafty-controller) |
| Steam Headless | Herramientas para Steam | Servidor remoto de Steam sin cabeza (headless) mediante Docker. | Permite gestionar juegos de Steam en un servidor remoto. | Usuarios que quieren acceder a su biblioteca de Steam desde un servidor. | [GitHub - Steam Headless](https://github.com/steamheadless/steamheadless) |
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
## Dependencias nativas para tests de integración
## Project Structure
Algunos tests de integración (p. ej. verificación de DATs, lectura de CHD/7z)
requieren herramientas nativas instaladas en el sistema donde se ejecuten
los tests (local o CI). A continuación está la lista mínima y cómo instalarlas:
```
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
```
- `7z` / `p7zip` — necesario para extraer/leer ZIP y 7z.
- Debian/Ubuntu: `sudo apt update && sudo apt install -y p7zip-full p7zip-rar`
- macOS (Homebrew): `brew install p7zip`
## Configuration
- `chdman` — herramienta de MAME para manejar archivos CHD (opcional,
requerida para tests que trabajen con imágenes CHD).
- Debian/Ubuntu: intentar `sudo apt install -y mame-tools` o `sudo apt install -y mame`.
- macOS (Homebrew): `brew install mame`
- Si no hay paquete disponible, descargar o compilar MAME/CHDTools desde
las fuentes oficiales.
### Environment Variables
Notas:
Copy `.env.example` to `.env.local` (or `.env.development`) and fill in:
- En CI se intentará instalar estas herramientas cuando sea posible; si no
están disponibles los tests de integración que dependan de ellas pueden
configurarse para ejecutarse condicionalmente.
- La variable de entorno `INTEGRATION=1` controla si se ejecutan pruebas
más pesadas y dependientes de binarios.
```env
# 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
```bash
# 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](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](SECURITY.md).
## Documentation
- **[SECURITY.md](SECURITY.md)** — Security policies and best practices
- **[docs/API_KEYS.md](docs/API_KEYS.md)** — How to obtain and configure API credentials
- **[docs/architecture.md](docs/architecture.md)** — System architecture and design decisions
- **[docs/data-model.md](docs/data-model.md)** — Database schema and entities
- **[docs/requirements.md](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
```bash
# 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](/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 ✅