368 lines
9.6 KiB
Markdown
368 lines
9.6 KiB
Markdown
# 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
|
||
- <20>️ **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
|
||
|
||
```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
|
||
|
||
# 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
|
||
|
||
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/ # 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:
|
||
|
||
```env
|
||
# 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](docs/02-tecnico/apis.md)**.
|
||
|
||
## Testing
|
||
|
||
### General Tests
|
||
|
||
```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
|
||
```
|
||
|
||
### Frontend Development and Testing
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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](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](SECURITY.md).
|
||
|
||
## Documentation
|
||
|
||
- **[SECURITY.md](SECURITY.md)** — Security policies and best practices
|
||
- **[docs/README.md](docs/README.md)** — Documentation index and navigation guide
|
||
- **[docs/01-conceptos/requirements.md](docs/01-conceptos/requirements.md)** — Project requirements and use cases
|
||
- **[docs/01-conceptos/architecture.md](docs/01-conceptos/architecture.md)** — System architecture and design decisions
|
||
- **[docs/01-conceptos/data-model.md](docs/01-conceptos/data-model.md)** — Database schema and entities
|
||
- **[docs/02-tecnico/apis.md](docs/02-tecnico/apis.md)** — APIs configuration and integration guide
|
||
- **[docs/02-tecnico/frontend.md](docs/02-tecnico/frontend.md)** — Complete frontend architecture and implementation
|
||
- **[docs/03-analisis/competitive-analysis.md](docs/03-analisis/competitive-analysis.md)** — Market analysis and competitive research
|
||
|
||
## 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) — 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 ✅
|