ALFA MVP

MVP backend-first para reportes de incidencias relacionadas con animales, con portal publico lean y backoffice minimo. La documentacion en docs/ es la fuente de verdad de alcance, API y modelo de datos.

Estructura del repositorio

• apps/api API REST en NestJS (backend)
• apps/web app Next.js (frontend)
• docs documentos de producto/arquitectura/API y criterios de aceptacion

Requisitos

• Docker + Docker Compose
• Node.js 20 (requerido para desarrollo local fuera de Docker)

Desarrollo local en WSL

Si trabajas fuera de Docker en WSL, usa Node/npm nativos de Linux dentro de la distro. Una opcion simple es nvm:

export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
nvm install 20
nvm alias default 20

Verifica que el shell use binarios Linux:

which node
which npm
node -v
npm -v

Inicio rapido (Docker)

docker compose up --build

• API: http://localhost:3001/api/v1
• Swagger: http://localhost:3001/api/docs
• Web: http://localhost:3000
• MinIO (S3 local): http://localhost:9000 (console: http://localhost:9001)
  • Bucket precreado: alfa-evidence
  • Console login: alfa / alfa-minio (verifica el bucket en Buckets)
  • CLI (AWS): AWS_ACCESS_KEY_ID=alfa AWS_SECRET_ACCESS_KEY=alfa-minio aws s3 ls --endpoint-url http://localhost:9000
  • Script: ./scripts/verify-minio.sh

Configuracion de entorno

Copia .env.example a .env y ajusta DATABASE_URL.

• Postgres local (por defecto en Docker Compose):

DATABASE_URL=postgres://alfa:alfa@localhost:5432/alfa

• MinIO (S3 local por defecto en Docker Compose):

S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=alfa
S3_SECRET_KEY=alfa-minio
S3_BUCKET=alfa-evidence
S3_REGION=us-east-1

• Storage local por filesystem (fallback cuando no configuras S3_*):

LOCAL_STORAGE_DIR=apps/api/.storage
API_BASE_URL=http://localhost:3001

• Rate limiting y retry de notificaciones:

RATE_LIMIT_REPORTS_MAX=10
RATE_LIMIT_REPORTS_WINDOW_MS=60000
RATE_LIMIT_EVIDENCE_MAX=10
RATE_LIMIT_EVIDENCE_WINDOW_MS=60000
NOTIFICATION_RETRY_INTERVAL_MS=5000

• Tests (override opcional):

S3_ENDPOINT_TEST=http://localhost:9000
S3_ACCESS_KEY_TEST=alfa
S3_SECRET_KEY_TEST=alfa-minio
S3_BUCKET_TEST=alfa-evidence
S3_REGION_TEST=us-east-1

• Supabase (ejemplo):

DATABASE_URL=postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=require

Flujo TDD

Este proyecto usa TDD: empieza con un test fallando, implementa, corre tests, corrige hasta verde y solo entonces marca la tarea como completa.

Desarrollo API

• Prefijo global: /api/v1
• Swagger habilitado en /api/docs
• Metricas internas: /api/v1/internal/metrics
• Auditoria admin: /api/v1/admin/audit

Prisma

Desde apps/api:

npm run prisma:migrate:dev
npm run prisma:migrate:deploy
npm run prisma:generate

Tests

Tests unitarios del API:

npm test -w apps/api -- --runInBand

Typecheck del API sin emitir artefactos:

npx tsc -p apps/api/tsconfig.build.json --noEmit --incremental false

E2E en Docker:

docker compose -f docker-compose.test.yml up --build --abort-on-container-exit

Si corres E2E fuera de Docker, debes tener DATABASE_URL apuntando a un PostgreSQL accesible y, si quieres S3 local, MinIO levantado.

E2E UI (Playwright) en Docker:

docker compose -f docker-compose.playwright.yml up --build --abort-on-container-exit

Estado del proyecto

Ver docs/STATUS.md para tareas completas y pendientes.