Saltar a contenido

Arquitectura del backend

El backend de KanjiIQ es una REST API Dart Frog que sirve contenido de tarjetas de estudio, gestiona configuraciones de locale y proporciona analítica de administración.

Estructura de la API

/api/v1/
├── config/
│   └── locale/[locale]              # GET - Locale configuration
├── kanji/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single kanji
│   └── random/index                 # GET - Random batch
├── vocabulary/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single vocabulary
│   └── random/index                 # GET - Random batch
└── admin/                           # Protected routes (API key required)

Pila de middleware

Cada solicitud pasa por un pipeline de middleware en capas definido en _middleware.dart:

graph TD
    R[Incoming Request] --> M1[ipBlocklistCheck]
    M1 -->|Blocked IP| R404[404 Response]
    M1 -->|Allowed| M2[securityMiddleware]
    M2 -->|Malicious Path| R404
    M2 -->|Clean| M3[corsHeaders]
    M3 --> M4[regionalAnalytics]
    M4 --> M5[requestLogger]
    M5 --> M6[databaseProvider]
    M6 --> H[Route Handler]

Detalles del middleware

Middleware Propósito
ipBlocklistCheck Rechaza solicitudes de direcciones IP bloqueadas (manual + auto-bloqueadas)
securityMiddleware Bloquea probes de extensiones de archivo maliciosas, detecta patrones de inyección SQL, previene path traversal
corsHeaders Añade cabeceras CORS para solicitudes cross-origin
regionalAnalytics Rastrea el origen de las solicitudes (país, tipo de dispositivo, hash de IP), marca actividad sospechosa, auto-bloquea infractores reincidentes
requestLogger Registra todas las solicitudes con información de tiempo
databaseProvider Inicializa el pool de conexiones PostgreSQL

Middleware de administración

Las rutas de administración (/api/v1/admin/*) tienen protección adicional:

  • Autenticación por clave API mediante la cabecera X-API-Key
  • Limitación de velocidad más estricta (50 req/min vía Traefik)
  • Exentas del auto-bloqueo (para evitar bloquear a los administradores)

Conexión a la base de datos

El backend resuelve las credenciales de la base de datos en orden de prioridad:

  1. Variable de entorno DATABASE_URL (producción — inyectada desde Kubernetes Secret)
  2. Variables de entorno individuales: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
  3. Valores por defecto: localhost:5432

Funciones de seguridad

Detección de rutas maliciosas

Devuelve 404 para solicitudes que buscan scripts del lado del servidor, archivos de configuración sensibles y endpoints de frameworks comunes que no existen en este stack.

Auto-bloqueo

El middleware de analítica implementa bloqueo automático de IP:

  1. Cada solicitud sospechosa se marca en la tabla regional_analytics
  2. Las IPs que acumulan solicitudes sospechosas por encima de un umbral configurable se añaden automáticamente a la lista de bloqueo
  3. Los auto-bloqueos expiran después de una duración configurable
  4. Las rutas de administración están exentas para evitar el auto-bloqueo

Cumplimiento de privacidad

Los datos de analítica siguen los requisitos de GDPR/CCPA:

  • Las direcciones IP sin procesar se retienen solo durante 7 días
  • Después de 7 días, las IPs se reemplazan con hashes SHA-256
  • La geolocalización a nivel de país usa la cabecera CF-IPCountry de Cloudflare (sin bases de datos de geolocalización de IP)
  • Los usuarios pueden solicitar la eliminación de datos a través de la API de administración