workspace-v1/projects/gamilit/apps/backend/service.descriptor.yml

# ==============================================================================
# SERVICE DESCRIPTOR - GAMILIT API
# ==============================================================================
# Documento de referencia para el servicio backend de Gamilit
# Mantenido por: Backend-Agent
# Actualizado: 2025-12-18
# ==============================================================================

version: "1.0.0"

# ------------------------------------------------------------------------------
# IDENTIFICACION DEL SERVICIO
# ------------------------------------------------------------------------------
service:
  name: "gamilit-api"
  display_name: "Gamilit API"
  description: "API REST para la plataforma de gamificacion educativa"
  type: "backend"
  runtime: "node"
  framework: "nestjs"
  owner_agent: "NEXUS-BACKEND"

# ------------------------------------------------------------------------------
# CONFIGURACION DE PUERTOS
# ------------------------------------------------------------------------------
ports:
  internal: 3000
  registry_ref: "projects.gamilit.services.api"
  protocol: "http"

# ------------------------------------------------------------------------------
# CONFIGURACION DE BASE DE DATOS
# ------------------------------------------------------------------------------
database:
  registry_ref: "gamilit"
  schemas:
    - "public"
    - "auth"
    - "gamification"
    - "progress"
    - "content"
  role: "runtime"

# ------------------------------------------------------------------------------
# DEPENDENCIAS
# ------------------------------------------------------------------------------
dependencies:
  services:
    - name: "postgres"
      type: "database"
      required: true
    - name: "redis"
      type: "cache"
      required: false

  packages:
    runtime:
      - "@nestjs/core"
      - "@nestjs/platform-express"
      - "@nestjs/typeorm"
      - "typeorm"
      - "pg"
      - "redis"
      - "bcrypt"
      - "jsonwebtoken"
    development:
      - "typescript"
      - "jest"
      - "@types/node"

# ------------------------------------------------------------------------------
# ENDPOINTS
# ------------------------------------------------------------------------------
endpoints:
  health:
    path: "/health"
    method: "GET"
    auth: false
    description: "Health check endpoint"

  api_prefix: "/api/v1"

  modules:
    auth:
      prefix: "/auth"
      endpoints:
        - { path: "/login", method: "POST", auth: false }
        - { path: "/register", method: "POST", auth: false }
        - { path: "/refresh", method: "POST", auth: true }
        - { path: "/logout", method: "POST", auth: true }

    users:
      prefix: "/users"
      endpoints:
        - { path: "/", method: "GET", auth: true, roles: ["admin"] }
        - { path: "/:id", method: "GET", auth: true }
        - { path: "/me", method: "GET", auth: true }
        - { path: "/:id", method: "PUT", auth: true }

    courses:
      prefix: "/courses"
      endpoints:
        - { path: "/", method: "GET", auth: true }
        - { path: "/:id", method: "GET", auth: true }
        - { path: "/", method: "POST", auth: true, roles: ["instructor", "admin"] }
        - { path: "/:id/enroll", method: "POST", auth: true }

    progress:
      prefix: "/progress"
      endpoints:
        - { path: "/", method: "GET", auth: true }
        - { path: "/course/:courseId", method: "GET", auth: true }
        - { path: "/lesson/:lessonId/complete", method: "POST", auth: true }

    achievements:
      prefix: "/achievements"
      endpoints:
        - { path: "/", method: "GET", auth: true }
        - { path: "/user/:userId", method: "GET", auth: true }

    leaderboards:
      prefix: "/leaderboards"
      endpoints:
        - { path: "/", method: "GET", auth: true }
        - { path: "/course/:courseId", method: "GET", auth: true }

# ------------------------------------------------------------------------------
# CONFIGURACION
# ------------------------------------------------------------------------------
config:
  environment_variables:
    required:
      - name: "DATABASE_URL"
        description: "PostgreSQL connection string"
      - name: "JWT_SECRET"
        description: "Secret for JWT signing"
    optional:
      - name: "PORT"
        default: "3000"
      - name: "REDIS_URL"
        default: "redis://localhost:6379"
      - name: "JWT_EXPIRES_IN"
        default: "1d"
      - name: "LOG_LEVEL"
        default: "info"
      - name: "CORS_ORIGIN"
        default: "http://gamilit.localhost"

# ------------------------------------------------------------------------------
# DOCKER
# ------------------------------------------------------------------------------
docker:
  image: "gamilit-api"
  dockerfile: "Dockerfile"
  build_args:
    - "NODE_ENV"
  networks:
    - "gamilit_${ENV:-local}"
    - "infra_shared"
  labels:
    traefik:
      enable: true
      router: "gamilit-api"
      rule: "Host(`api.gamilit.localhost`)"
      entrypoints: "web"

# ------------------------------------------------------------------------------
# HEALTH CHECK
# ------------------------------------------------------------------------------
healthcheck:
  endpoint: "/health"
  interval: "30s"
  timeout: "5s"
  retries: 3
  start_period: "10s"

# ------------------------------------------------------------------------------
# ESTADO
# ------------------------------------------------------------------------------
status:
  phase: "development"
  version: "0.1.0"
  last_updated: "2025-12-18"
  completeness: 20

# ------------------------------------------------------------------------------
# METADATA
# ------------------------------------------------------------------------------
metadata:
  created_at: "2025-12-18"
  created_by: "Backend-Agent"
  project: "gamilit"
  team: "gamilit-team"