# Arquitectura — Diseño técnico de alto nivel

## Visión general

Arquitectura pensada para un **MVP local-first / self-hosted** que pueda evolucionar a un servicio multiusuario. Propuesta: **monorepo** con dos paquetes principales: `/backend` y `/frontend` (Yarn workspaces). Backend expone una REST API (Fastify + TypeScript); Frontend es una SPA en React (Vite o similar) usando **TanStack Query** y **TanStack Router**.

## Diagrama de alto nivel (texto)

```
Usuario (Browser React) ↔ Frontend (TanStack Query/Router) ↔ Backend REST (Fastify + TypeScript)
                                 ↕
                Worker (Bull/BullMQ) ↔ Redis (cache/cola, opcional)
                                 ↕
          DB (SQLite dev → Postgres prod) + Storage (local FS | S3)
                                 ↕
                     APIs externas (IGDB, RAWG, TheGamesDB)
```

---

## Decisiones clave y justificación

- **Monorepo (Yarn workspaces)**: coherencia de versiones, compartir utilidades y configuración (lint/tsconfig).
- **Fastify + TypeScript** (REST): recomendado para rendimiento y ergonomía con TypeScript; ofrece sistema de plugins encapsulados, validación/serialización basada en Ajv integrada, logging muy rápido (pino) y mejor throughput en producción.
- **Prisma** como ORM: productivo y portátil entre SQLite/Postgres.
- **SQLite en dev / Postgres en producción**: facilidad de desarrollo y migraciones seguras para futuro.
- **Bull/BullMQ + Redis** para trabajos asíncronos (escaneo, enrich, procesamiento de imágenes).
- **Storage**: Adapter pattern para `StorageAdapter` que permita usar S3 o disco local según despliegue.

---

## Stack propuesto (resumen)

- Backend: Node.js, TypeScript, Fastify, Prisma, Bull/BullMQ, Redis (opcional), Sharp (procesado de imágenes), @fastify/multipart (uploads), @fastify/helmet, @fastify/rate-limit, Ajv (validación), pino (logging).
- Frontend: React, TypeScript (opcional), Vite, TanStack Query, TanStack Router, Tailwind CSS (opcional).
- Infra / DevOps: Docker Compose (self-hosting), GitHub Actions (CI), env vars + GitHub Secrets.

---

## Estructura de carpetas sugerida

```
/ (monorepo)
  package.json (workspaces)
  /backend
    package.json
    prisma/schema.prisma
    src/
      index.ts
      controllers/
      services/
      routes/
      jobs/
      workers/
      lib/
  /frontend
    package.json
    src/
      routes/
      components/
      hooks/
      lib/
      assets/
  /docs
```

---

## Scripts útiles sugeridos (`package.json` raíz)

```json
{
  "scripts": {
    "dev": "concurrently \"yarn dev:backend\" \"yarn dev:frontend\"",
    "dev:backend": "cd backend && ts-node-dev --respawn src/index.ts",
    "dev:frontend": "cd frontend && vite",
    "start": "node backend/dist/index.js",
    "lint": "eslint . --ext .ts,.tsx,.js",
    "format": "prettier --write .",
    "prisma:migrate": "cd backend && prisma migrate dev",
    "prisma:studio": "cd backend && prisma studio"
  }
}
```

---

## Seguridad y operacionales

- Variables sensibles en `.env` y en GitHub Secrets para CI.
- CORS configurado para orígenes permitidos; validación y saneamiento de entradas.
- Rate limiting global y por endpoint (enriquecimiento de metadatos).
- Backups: snapshots regulares de la DB y copia periódica de carpeta `artwork/`.
- Despliegue: `docker-compose.yml` con volúmenes para DB y assets; salud (`/health`) y readiness probes.
- Observabilidad: logs estructurados (pino/winston); endpoint de métricas básico (Prometheus) o integraciones simples.

---

## Integración de APIs externas

- Encapsular cada proveedor en un adaptador (ej.: `IgdbClient`, `RawgClient`) con interfaz común: `search(query)`, `getById(id)`, `getArtwork(id)`.
- Caching: Redis o LRU en memoria con TTL (ej. 24h) para respuestas y metadatos de artwork.
- Retries y protección: reconectar con backoff + circuit breaker para evitar fallos en cascada.

---

## Fuentes

- Documentación: Fastify, Prisma, Bull/BullMQ, Redis, Sharp, TanStack Query/Router.

---

**Metadatos**
Autor: Quasar (investigación automatizada)
Última actualización: 2026-02-07