Klerk

Klerk es el backend del sistema Kire / LearnYos: API educativa con IA que genera exámenes (quiz e ICFES), flashcards y notas desde un tema o archivo, con chat educativo en streaming, créditos diarios y comunidad. Documentado en README y ARCHITECTURE.md.

Decisión clave: monolito modular NestJS en vez de microservicios, para que un solo desarrollador pueda mantener 11 dominios con un único deploy y una sola base PostgreSQL.

Propósito declarado: Servir y persistir todo el dominio educativo de LearnYos y orquestar la generación con IA (exámenes, flashcards, notas, chat) con control de costos por créditos.

Monolito modular NestJS 10 por features (auth, users, exams, flash-cards, notes, messages, gemini, credits, likes, global-chat, exam-attempts). TypeORM + PostgreSQL, ValidationPipe estricta, Helmet, rate-limit por endpoint, ApiKeyGuard global + JWT.

┌──────────┐  HTTPS + x-api-key + JWT  ┌─────────────────────────────────┐
│ Frontend │ ────────────────────────▶ │ Klerk API (NestJS 10, Express)    │
│ LearnYos │                            │ auth │ users │ exams │ flash-cards │
└──────────┘                            │ notes │ messages │ gemini │ credits │
                                        │ likes │ global-chat │ exam-attempts │
                                        └──────┬──────────────┬───────────────┘
                                               │              │
                                    ┌──────────▼─────┐ ┌──────▼──────────────┐
                                    │  PostgreSQL    │ │ Gemini API (rotación│
                                    │  TypeORM       │ │ keys + fallback) +  │
                                    └────────────────┘ │ SMTP + Google OAuth │
                                                       └─────────────────────┘

• Capas por módulo: *.controller.ts (HTTP, DTOs, guards) → *.service.ts (negocio) → entities/*.entity.ts (TypeORM) → dto/*.dto.ts (class-validator). Transversal en src/common (guards, filtros, decoradores, storage).
• Arranque en src/main.ts: CORS por env, rate-limit por ruta sensible, Helmet con CSP, ValidationPipe global (whitelist + forbidNonWhitelisted + transform), sanitización XSS, AllExceptionsFilter y ApiKeyGuard global.
• Módulo gemini centraliza prompts (AI_PROMPTS.ts), salida JSON por responseSchema, JsonExtractor anti-markdown, multimodal base64 y streaming SSE vía generateContentStream.

• auth: Registro/login local, Google (código e ID token), invitados, refresh, verificación email.
• users: CRUD + borrado lógico pendingDeletion.
• exams: Exámenes quiz/ICFES con Exam → ExamQuestion → ExamOption.
• flash-cards: Mazos Card → FlashCard.
• notes: Note → NoteContent (Markdown enriquecido).
• messages: Chats con IA en JSON o SSE, con archivos adjuntos.
• gemini: Wrapper IA: prompts, schemas, rotación, multimodal, streaming.
• credits: 30 créditos/día por usuario para generación.
• likes: Likes polimórficos exam|card|note con UNIQUE(userId, cardType, cardId).
• global-chat: Chat comunitario.
• exam-attempts: Intentos + estadísticas; formatters deck/exam.

User 1──* Note 1──1 NoteContent
User 1──* Exam 1──* ExamQuestion 1──* ExamOption
User 1──* Card 1──* FlashCard
User 1──* Chat 1──* Message
User 1──* DailyCredits · CardLike · ExamAttempt
Códigos de 5 caracteres en Note/Exam/Card para compartir.

• Índices en userId y createdAt; cascadas en hijos; UNIQUE en likes para evitar dobles.
• Uploads en /uploads servidos estático + enviados en base64 a Gemini para análisis multimodal.

• ApiKeyGuard global exige x-api-key salvo /health, /ping, /auth/* o JWT válido.
• JwtGuard / JwtAuthGuard / RequireAuthGuard + decoradores @RequireAuth/@AllowGuest para bloquear invitados donde no apliquen.
• Límite 1 MB por body (413), sanitización <script>/on*= en body permitiendo Markdown, TypeORM parametrizado anti-SQLi, frameguard deny.

Dónde: Render/Railway/VPS + PostgreSQL gestionado (Aiven/Neon con SSL)

• pnpm install --frozen-lockfile && pnpm build
• NODE_ENV=production, synchronize=false + migraciones TypeORM
• Reverse proxy Nginx/Caddy con HTTPS; BACKEND_URL al dominio público
• Puerto configurable (default 2300)

Variables de entorno clave (.env — tú pones los valores):

DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME
JWT_SECRET, JWT_EXPIRATION, API_KEY
GEMINI_API_KEY, GEMINI_API_KEY_2
GOOGLE_CLIENT_ID/SECRET, MAIL_USER/MAIL_PASS, CORS_ORIGINS

• Docs como código: README y ARCHITECTURE.md se actualizan con cada módulo para mantener la documentación al día sin leer todo el código.
• Seguridad por defecto: todo cerrado salvo lo explícitamente público; validación estricta que rechaza propiedades extra.
• Economía de IA: créditos + rate-limit + rotación de keys para no quemar cuota en un abuso.

• Diseño de APIs modulares NestJS a escala (11 dominios).
• Orquestación de LLMs en producción: prompts, schemas, streaming y costos.
• Endurecimiento real: Helmet, rate-limit granular, XSS, ApiKey global.

git clone https://github.com/xenoxf/klerk && cd klerk
pnpm install
cp .env.example .env y completar DB, JWT_SECRET, API_KEY, GEMINI_API_KEY(s)
pnpm run start:dev → http://localhost:2300

• Migraciones TypeORM versionadas para producción.
• Cola (BullMQ) para generaciones largas con reintentos.
• Evaluación automática de calidad de exámenes generados.