# 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
- �️ **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 ✅