feat: replace fixed login rate limit with progressive lockout

Made-with: Cursor

.env.example

@@ -0,0 +1,44 @@
+# Server
+PORT=3000
+HOST=0.0.0.0
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://samreshu:samreshu_dev@localhost:5432/samreshu
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Auth
+JWT_SECRET=dev-secret-change-in-production-min-32-chars
+JWT_ACCESS_TTL=15m
+JWT_REFRESH_TTL=7d
+
+# LLM
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_MODEL=qwen2.5:14b
+LLM_API_KEY=
+LLM_TIMEOUT_MS=15000
+LLM_MAX_RETRIES=1
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=2048
+
+# Rate limits (login uses progressive lockout: 5/10/20 failed attempts -> 15m/1h/24h block)
+RATE_LIMIT_REGISTER=3
+RATE_LIMIT_FORGOT_PASSWORD=3
+RATE_LIMIT_VERIFY_EMAIL=5
+RATE_LIMIT_API_AUTHED=100
+RATE_LIMIT_API_GUEST=30
+
+# CORS (comma-separated origins)
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+
+# Email (dev — mailpit / mailtrap)
+SMTP_HOST=localhost
+SMTP_PORT=1025
+SMTP_USER=
+SMTP_PASS=
+EMAIL_FROM=noreply@samreshu.dev
+
+# Sentry (optional for dev)
+SENTRY_DSN=

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "samreshu_docs"]
+	path = samreshu_docs
+	url = https://git.vakanaut.ru/admin/samreshu_docs.git

AGENT_TASKS.md

@@ -0,0 +1,307 @@
+# Распределение задач по агентам (MVP 0)
+
+Документ для параллельной работы нескольких агентов. Каждый агент работает в **отдельной сессии Cursor** (отдельное окно чата). После выполнения **каждой задачи** — отдельный коммит по conventional commits.
+
+## Как запустить агента
+
+1. Открыть **новую сессию чата** (новое окно Composer/Chat в Cursor)
+2. Скопировать промпт для нужного агента из раздела ниже
+3. Агент выполнит свои задачи и сделает коммиты
+4. Повторить для следующего агента
+
+### Промпты для запуска агентов
+
+**Agent A (Infrastructure):**
+
+```text
+Implement Agent A tasks from AGENT_TASKS.md. Work in branch feat/infra-core. 
+Do tasks A1–A9 in order. After EACH task, run: git add -A && git commit -m "<message from table>".
+Use conventional commits. Do not touch schema or auth/tests/profile/llm/admin code.
+```
+
+**Agent B (DB Schema):**
+
+```text
+Implement Agent B tasks from AGENT_TASKS.md. Work in branch feat/db-schema. 
+Do tasks B1–B7. After EACH task, commit with the message from the table.
+Assume Agent A has created plugins. Generate migrations with npm run db:generate.
+```
+
+**Agent C (Auth):**
+
+```text
+Implement Agent C tasks from AGENT_TASKS.md. Work in branch feat/auth. 
+Merge or rebase from dev first. Do tasks C1–C7, commit after each.
+```
+
+**Agent D (Profile):**
+
+```text
+Implement Agent D tasks from AGENT_TASKS.md. Work in branch feat/profile-subscription.
+Merge dev first. Do tasks D1–D5, commit after each.
+```
+
+**Agent E (Tests & Questions):**
+
+```text
+Implement Agent E tasks from AGENT_TASKS.md. Work in branch feat/tests-questions.
+Requires Auth, Profile, LLM done. Do E1–E5, commit after each.
+```
+
+**Agent F (LLM):**
+
+```text
+Implement Agent F tasks from AGENT_TASKS.md. Work in branch feat/llm-service.
+Do F1–F5, commit after each. Export LlmService interface for QuestionService.
+```
+
+**Agent G (Admin):**
+
+```text
+Implement Agent G tasks from AGENT_TASKS.md. Work in branch feat/admin-qa.
+Do G1–G4, commit after each.
+```
+
+**Agent H (Testing):**
+
+```text
+Implement Agent H tasks from AGENT_TASKS.md. Work in branch feat/testing.
+Do H1–H7, commit after each. Target ≥70% coverage on services.
+```
+
+## Текущее состояние репозитория
+
+Часть работы уже выполнена одним агентом:
+
+- **Infra (A):** package.json, config, plugins (database, redis, security, rateLimit), app.ts, server.ts, utils/errors, utils/uuid, docker-compose, .env.example
+- **Schema (B):** все схемы в src/db/schema, drizzle.config, migrate.ts. Миграции ещё не сгенерированы (нужен `npm run db:generate`)
+
+Агентам B–H при старте: проверить, что уже есть, и дописать недостающее. Не дублировать сделанное. Коммитить только свои изменения.
+
+---
+
+## Формат коммитов
+
+Использовать [conventional commits](samreshu_docs/principles/git-workflow.md):
+
+- `feat:` — новый функционал
+- `fix:` — исправление бага
+- `refactor:` — рефакторинг
+- `chore:` — инфраструктура, зависимости, конфиг
+- `test:` — тесты
+
+Примеры: `feat: add auth register endpoint`, `chore: add database plugin`, `test: add auth service unit tests`.
+
+---
+
+## Волны запуска и зависимости
+
+```text
+Волна 1 (старт сразу, параллельно):
+  Agent A ────────────────────────────►
+  Agent B ────────────────────────────►
+
+Волна 2 (после завершения A + B):
+  Agent C ────────────────────────────►
+  Agent D ────────────────────────────►
+  Agent F ────────────────────────────►
+
+Волна 3 (после C, D, F):
+  Agent E ────────────────────────────►
+  Agent G ────────────────────────────►
+  Agent H ────────────────────────────► (может стартовать частично после C)
+```
+
+---
+
+## Agent A: Infrastructure & Core Backend
+
+**Зависимости:** нет (запускать первым)
+
+**Ветка:** `feat/infra-core` (создать от `main`/`dev`)
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| A1 | package.json, tsconfig, .nvmrc, .gitignore | `chore: init project with Fastify and TypeScript` |
+| A2 | src/config/env.ts с Zod-валидацией | `chore: add env config with validation` |
+| A3 | src/plugins/redis.ts | `feat: add Redis plugin` |
+| A4 | src/plugins/database.ts | `feat: add database plugin with Drizzle` |
+| A5 | src/plugins/security.ts (helmet + cors) | `feat: add security plugin` |
+| A6 | src/plugins/rateLimit.ts | `feat: add rate limit plugin with Redis` |
+| A7 | src/utils/errors.ts, src/utils/uuid.ts | `chore: add error utils and uuid7 helper` |
+| A8 | src/app.ts — error handler, логирование | `feat: add Fastify app with error handler` |
+| A9 | src/server.ts, docker-compose.dev.yml, .env.example | `chore: add server entry and dev docker compose` |
+
+**Итого:** 9 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent B: Data Model & Drizzle Schema
+
+**Зависимости:** Agent A (нужен database plugin). Может стартовать после A4.
+
+**Ветка:** `feat/db-schema`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| B1 | src/db/schema/enums.ts | `feat: add Drizzle enums for schema` |
+| B2 | src/db/schema/users.ts, sessions.ts, subscriptions.ts | `feat: add users and auth tables schema` |
+| B3 | src/db/schema/tests.ts, testQuestions.ts | `feat: add tests and test_questions schema` |
+| B4 | src/db/schema/questionBank.ts, questionCacheMeta.ts, questionReports.ts | `feat: add question bank schema` |
+| B5 | src/db/schema/userStats.ts, auditLogs.ts, userQuestionLog.ts, verificationTokens.ts | `feat: add user_stats, audit_logs and verification tokens schema` |
+| B6 | src/db/schema/index.ts, drizzle.config.ts, migrate.ts | `chore: wire schema and migrations` |
+| B7 | Генерация миграций (npm run db:generate), seed скрипт | `chore: add initial migration and seed script` |
+
+**Итого:** 7 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent C: Auth & Sessions Service
+
+**Зависимости:** A, B завершены.
+
+**Ветка:** `feat/auth`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| C1 | src/utils/password.ts (argon2id), src/utils/jwt.ts | `feat: add password hashing and JWT utils` |
+| C2 | src/services/auth/auth.service.ts | `feat: add AuthService` |
+| C3 | src/plugins/auth.ts (JWT verify, request.user) | `feat: add auth plugin` |
+| C4 | src/routes/auth.ts — register, login, logout, refresh | `feat: add auth routes` |
+| C5 | verify-email, forgot-password, reset-password | `feat: add email verification and password reset` |
+| C6 | Rate limiting на auth-роуты | `feat: add rate limiting to auth endpoints` |
+| C7 | Регистрация auth routes в app | `feat: register auth routes in app` |
+
+**Итого:** 7 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent D: Profile & Subscription Middleware
+
+**Зависимости:** A, B, C.
+
+**Ветка:** `feat/profile-subscription`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| D1 | src/plugins/subscription.ts | `feat: add subscription middleware` |
+| D2 | src/services/user/user.service.ts | `feat: add UserService` |
+| D3 | src/routes/profile.ts — GET, PATCH, GET :username | `feat: add profile routes` |
+| D4 | Интеграция user_stats в профиль | `feat: add stats to profile response` |
+| D5 | Регистрация profile routes в app | `feat: register profile routes` |
+
+**Итого:** 5 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent E: Question Bank & Tests Service
+
+**Зависимости:** A, B, C, D, F (контракт LlmService).
+
+**Ветка:** `feat/tests-questions`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| E1 | src/services/questions/question.service.ts | `feat: add QuestionService` |
+| E2 | src/services/tests/tests.service.ts — создание теста, снепшот | `feat: add TestsService create flow` |
+| E3 | tests.service — answer, finish, history | `feat: add test answer and finish flow` |
+| E4 | src/routes/tests.ts | `feat: add tests routes` |
+| E5 | Регистрация tests routes | `feat: register tests routes` |
+
+**Итого:** 5 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent F: LLM Service & Fallback Logic
+
+**Зависимости:** A, B.
+
+**Ветка:** `feat/llm-service`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| F1 | src/services/llm/llm.service.ts — конфиг, HTTP client | `feat: add LlmService base` |
+| F2 | generateQuestions с JSON Schema валидацией | `feat: add LLM question generation` |
+| F3 | Retry и fallback логика | `feat: add LLM retry and fallback` |
+| F4 | Интеграция question_cache_meta | `feat: log LLM metadata to question_cache_meta` |
+| F5 | Экспорт интерфейса для QuestionService | `feat: export LlmService interface` |
+
+**Итого:** 5 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Agent G: Admin QA for Questions
+
+**Зависимости:** A, B, C, E (модель question_bank).
+
+**Ветка:** `feat/admin-qa`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| G1 | src/services/admin/admin-question.service.ts | `feat: add AdminQuestionService` |
+| G2 | src/routes/admin/questions.ts | `feat: add admin questions routes` |
+| G3 | audit_logs при approve/reject/edit | `feat: add audit logging to admin actions` |
+| G4 | Регистрация admin routes | `feat: register admin routes` |
+
+**Итого:** 4 коммита. После завершения — PR в `dev`.
+
+---
+
+## Agent H: Tests & Quality
+
+**Зависимости:** Может стартовать после C (auth), наращивать по мере готовности других агентов.
+
+**Ветка:** `feat/testing`
+
+**Задачи и коммиты:**
+
+| # | Задача | Коммит |
+| - | - | - |
+| H1 | Vitest config, test-utils | `test: add Vitest config and test utils` |
+| H2 | AuthService unit tests | `test: add auth service tests` |
+| H3 | Auth routes integration tests | `test: add auth routes integration tests` |
+| H4 | TestsService и QuestionService tests | `test: add tests and questions service tests` |
+| H5 | LlmService unit tests (с моком) | `test: add LLM service tests` |
+| H6 | Admin routes integration tests | `test: add admin routes tests` |
+| H7 | Coverage ≥70%, npm script | `test: add coverage config` |
+
+**Итого:** 7 коммитов. После завершения — PR в `dev`.
+
+---
+
+## Рекомендуемый порядок запуска
+
+1. **Сразу:** Agent A и Agent B (в двух отдельных сессиях Cursor)
+2. **После A и B:** Agent C, D, F (три сессии)
+3. **После C, D, F:** Agent E, G (две сессии)
+4. **Параллельно волне 2–3:** Agent H (тесты по мере готовности API)
+
+---
+
+## Чеклист для каждого агента
+
+Перед каждым коммитом:
+
+- [ ] `npm run typecheck` проходит
+- [ ] Сообщение коммита по conventional commits
+- [ ] Нет `console.log`, только `logger`
+- [ ] Нет `any` без необходимости
+
+После завершения всех задач агента:
+
+- [ ] Создать PR в `dev`
+- [ ] Проверить, что не сломаны существующие тесты (если есть)

docker-compose.dev.yml

@@ -0,0 +1,29 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: samreshu
+      POSTGRES_PASSWORD: samreshu_dev
+      POSTGRES_DB: samreshu
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U samreshu -d samreshu"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:

drizzle.config.ts

@@ -0,0 +1,13 @@
+import 'dotenv/config';
+import { defineConfig } from 'drizzle-kit';
+
+const databaseUrl = process.env.DATABASE_URL ?? 'postgresql://samreshu:samreshu_dev@localhost:5432/samreshu';
+
+export default defineConfig({
+  schema: './src/db/schema/*.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: databaseUrl,
+  },
+});

package.json

@@ -8,7 +8,7 @@
     "build": "tsc",
     "dev": "tsx watch src/server.ts",
     "start": "node dist/server.js",
-    "db:generate": "drizzle-kit generate --config=drizzle.config.ts",
+    "db:generate": "tsx node_modules/drizzle-kit/bin.cjs generate --config=drizzle.config.ts",
     "db:migrate": "tsx src/db/migrate.ts",
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/db/seed.ts",

src/app.ts

@@ -0,0 +1,88 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { AppError } from './utils/errors.js';
+import databasePlugin from './plugins/database.js';
+import redisPlugin from './plugins/redis.js';
+import securityPlugin from './plugins/security.js';
+import rateLimitPlugin from './plugins/rateLimit.js';
+import authPlugin from './plugins/auth.js';
+import subscriptionPlugin from './plugins/subscription.js';
+import { authRoutes } from './routes/auth.js';
+import { profileRoutes } from './routes/profile.js';
+import { testsRoutes } from './routes/tests.js';
+import { adminQuestionsRoutes } from './routes/admin/questions.js';
+import { env } from './config/env.js';
+import { randomUUID } from 'node:crypto';
+
+export async function buildApp(): Promise<FastifyInstance> {
+  const isDev = env.NODE_ENV === 'development';
+
+  const app = Fastify({
+    logger: {
+      level: isDev ? 'debug' : 'info',
+      transport:
+        isDev
+          ? {
+              target: 'pino-pretty',
+              options: {
+                translateTime: 'HH:MM:ss Z',
+                ignore: 'pid,hostname',
+              },
+            }
+          : undefined,
+    },
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+    genReqId: () => randomUUID(),
+  });
+
+  app.setErrorHandler((err: unknown, request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    request.log.error({ err }, error.message);
+
+    if (err instanceof AppError) {
+      const statusCode = err.statusCode;
+      const payload = err.toJSON();
+      if (err.code === 'RATE_LIMIT_EXCEEDED' && 'retryAfter' in err) {
+        reply.header('Retry-After', String((err as AppError & { retryAfter?: number }).retryAfter ?? 60));
+      }
+      return reply.status(statusCode).send(payload);
+    }
+
+    if (error.validation) {
+      return reply.status(422).send({
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Validation failed',
+          details: error.validation,
+        },
+      });
+    }
+
+    const statusCode = error.statusCode ?? 500;
+    return reply.status(statusCode).send({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: env.NODE_ENV === 'production' ? 'Internal server error' : error.message,
+      },
+    });
+  });
+
+  app.addHook('onRequest', async (request, reply) => {
+    reply.header('x-request-id', request.id);
+  });
+
+  await app.register(redisPlugin);
+  await app.register(databasePlugin);
+  await app.register(securityPlugin);
+  await app.register(rateLimitPlugin);
+  await app.register(authPlugin);
+  await app.register(subscriptionPlugin);
+  await app.register(authRoutes, { prefix: '/auth' });
+  await app.register(profileRoutes, { prefix: '/profile' });
+  await app.register(testsRoutes, { prefix: '/tests' });
+  await app.register(adminQuestionsRoutes, { prefix: '/admin' });
+
+  app.get('/health', async () => ({ status: 'ok', timestamp: new Date().toISOString() }));
+
+  return app;
+}

src/config/env.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  PORT: z.coerce.number().min(1).max(65535).default(3000),
+  HOST: z.string().default('0.0.0.0'),
+
+  DATABASE_URL: z.string().min(1),
+  REDIS_URL: z.string().min(1).default('redis://localhost:6379'),
+
+  JWT_SECRET: z.string().min(32),
+  JWT_ACCESS_TTL: z.string().default('15m'),
+  JWT_REFRESH_TTL: z.string().default('7d'),
+
+  LLM_BASE_URL: z.string().url().default('http://localhost:11434/v1'),
+  LLM_MODEL: z.string().default('qwen2.5:14b'),
+  LLM_FALLBACK_MODEL: z.string().optional(),
+  LLM_API_KEY: z.string().optional(),
+  LLM_TIMEOUT_MS: z.coerce.number().default(15000),
+  LLM_MAX_RETRIES: z.coerce.number().min(0).default(1),
+  LLM_RETRY_DELAY_MS: z.coerce.number().min(0).default(1000),
+  LLM_TEMPERATURE: z.coerce.number().min(0).max(2).default(0.7),
+  LLM_MAX_TOKENS: z.coerce.number().default(2048),
+
+  RATE_LIMIT_REGISTER: z.coerce.number().default(3),
+  RATE_LIMIT_FORGOT_PASSWORD: z.coerce.number().default(3),
+  RATE_LIMIT_VERIFY_EMAIL: z.coerce.number().default(5),
+  RATE_LIMIT_API_AUTHED: z.coerce.number().default(100),
+  RATE_LIMIT_API_GUEST: z.coerce.number().default(30),
+
+  CORS_ORIGINS: z.string().default('http://localhost:5173'),
+  SENTRY_DSN: z.string().optional(),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+function parseEnv(): Env {
+  const result = envSchema.safeParse(process.env);
+  if (!result.success) {
+    const msg = result.error.flatten().fieldErrors;
+    throw new Error(`Invalid environment: ${JSON.stringify(msg)}`);
+  }
+  return result.data;
+}
+
+export const env = parseEnv();
+
+export function getCorsOrigins(): string[] {
+  return env.CORS_ORIGINS.split(',').map((s) => s.trim()).filter(Boolean);
+}

src/db/migrate.ts

@@ -0,0 +1,19 @@
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import pg from 'pg';
+import { env } from '../config/env.js';
+
+const { Pool } = pg;
+
+async function runMigrations() {
+  const pool = new Pool({ connectionString: env.DATABASE_URL });
+  const db = drizzle(pool);
+
+  await migrate(db, { migrationsFolder: './src/db/migrations' });
+  await pool.end();
+}
+
+runMigrations().catch((err) => {
+  console.error('Migration failed:', err);
+  process.exit(1);
+});

src/db/migrations/0000_fearless_salo.sql

@@ -0,0 +1,246 @@
+CREATE TYPE "public"."level" AS ENUM('basic', 'beginner', 'intermediate', 'advanced', 'expert');--> statement-breakpoint
+CREATE TYPE "public"."plan" AS ENUM('free', 'pro');--> statement-breakpoint
+CREATE TYPE "public"."question_source" AS ENUM('llm_generated', 'manual');--> statement-breakpoint
+CREATE TYPE "public"."question_status" AS ENUM('pending', 'approved', 'rejected');--> statement-breakpoint
+CREATE TYPE "public"."question_type" AS ENUM('single_choice', 'multiple_select', 'true_false', 'short_text');--> statement-breakpoint
+CREATE TYPE "public"."report_status" AS ENUM('open', 'resolved', 'dismissed');--> statement-breakpoint
+CREATE TYPE "public"."self_level" AS ENUM('jun', 'mid', 'sen');--> statement-breakpoint
+CREATE TYPE "public"."stack" AS ENUM('html', 'css', 'js', 'ts', 'react', 'vue', 'nodejs', 'git', 'web_basics');--> statement-breakpoint
+CREATE TYPE "public"."subscription_status" AS ENUM('active', 'trialing', 'cancelled', 'expired');--> statement-breakpoint
+CREATE TYPE "public"."test_mode" AS ENUM('fixed', 'infinite', 'marathon');--> statement-breakpoint
+CREATE TYPE "public"."test_status" AS ENUM('in_progress', 'completed', 'abandoned');--> statement-breakpoint
+CREATE TYPE "public"."user_role" AS ENUM('guest', 'free', 'pro', 'admin');--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "users" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"email" varchar(255) NOT NULL,
+	"password_hash" varchar(255) NOT NULL,
+	"nickname" varchar(30) NOT NULL,
+	"avatar_url" varchar(500),
+	"country" varchar(100),
+	"city" varchar(100),
+	"self_level" "self_level",
+	"is_public" boolean DEFAULT true NOT NULL,
+	"role" "user_role" DEFAULT 'free' NOT NULL,
+	"email_verified_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "sessions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"refresh_token_hash" varchar(255) NOT NULL,
+	"user_agent" varchar(500),
+	"ip_address" varchar(45),
+	"last_active_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "subscriptions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"plan" "plan" NOT NULL,
+	"status" "subscription_status" NOT NULL,
+	"started_at" timestamp with time zone NOT NULL,
+	"expires_at" timestamp with time zone,
+	"cancelled_at" timestamp with time zone,
+	"payment_provider" varchar(50),
+	"external_id" varchar(255),
+	CONSTRAINT "subscriptions_user_id_unique" UNIQUE("user_id")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "tests" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"stack" "stack" NOT NULL,
+	"level" "level" NOT NULL,
+	"question_count" integer NOT NULL,
+	"mode" "test_mode" DEFAULT 'fixed' NOT NULL,
+	"status" "test_status" DEFAULT 'in_progress' NOT NULL,
+	"score" integer,
+	"started_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"finished_at" timestamp with time zone,
+	"time_limit_seconds" integer
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "test_questions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"test_id" uuid NOT NULL,
+	"question_bank_id" uuid,
+	"order_number" integer NOT NULL,
+	"type" "question_type" NOT NULL,
+	"question_text" text NOT NULL,
+	"options" jsonb,
+	"correct_answer" jsonb NOT NULL,
+	"explanation" text NOT NULL,
+	"user_answer" jsonb,
+	"is_correct" boolean,
+	"answered_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "question_bank" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"stack" "stack" NOT NULL,
+	"level" "level" NOT NULL,
+	"type" "question_type" NOT NULL,
+	"question_text" text NOT NULL,
+	"options" jsonb,
+	"correct_answer" jsonb NOT NULL,
+	"explanation" text NOT NULL,
+	"status" "question_status" DEFAULT 'pending' NOT NULL,
+	"source" "question_source" NOT NULL,
+	"usage_count" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"approved_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "question_cache_meta" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"question_bank_id" uuid NOT NULL,
+	"llm_model" varchar(100) NOT NULL,
+	"prompt_hash" varchar(64) NOT NULL,
+	"generation_time_ms" integer NOT NULL,
+	"raw_response" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "question_reports" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"question_bank_id" uuid NOT NULL,
+	"user_id" uuid NOT NULL,
+	"reason" text NOT NULL,
+	"status" "report_status" DEFAULT 'open' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"resolved_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "user_stats" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"stack" "stack" NOT NULL,
+	"level" "level" NOT NULL,
+	"total_questions" integer DEFAULT 0 NOT NULL,
+	"correct_answers" integer DEFAULT 0 NOT NULL,
+	"tests_taken" integer DEFAULT 0 NOT NULL,
+	"last_test_at" timestamp with time zone,
+	CONSTRAINT "user_stats_user_id_stack_level_unique" UNIQUE("user_id","stack","level")
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "audit_logs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"admin_id" uuid NOT NULL,
+	"action" varchar(100) NOT NULL,
+	"target_type" varchar(50) NOT NULL,
+	"target_id" uuid NOT NULL,
+	"details" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "user_question_log" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"question_bank_id" uuid NOT NULL,
+	"seen_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "email_verification_codes" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"code" varchar(10) NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "password_reset_tokens" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" uuid NOT NULL,
+	"token_hash" varchar(255) NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "sessions" ADD CONSTRAINT "sessions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "subscriptions" ADD CONSTRAINT "subscriptions_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "tests" ADD CONSTRAINT "tests_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "test_questions" ADD CONSTRAINT "test_questions_test_id_tests_id_fk" FOREIGN KEY ("test_id") REFERENCES "public"."tests"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "test_questions" ADD CONSTRAINT "test_questions_question_bank_id_question_bank_id_fk" FOREIGN KEY ("question_bank_id") REFERENCES "public"."question_bank"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "question_cache_meta" ADD CONSTRAINT "question_cache_meta_question_bank_id_question_bank_id_fk" FOREIGN KEY ("question_bank_id") REFERENCES "public"."question_bank"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "question_reports" ADD CONSTRAINT "question_reports_question_bank_id_question_bank_id_fk" FOREIGN KEY ("question_bank_id") REFERENCES "public"."question_bank"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "question_reports" ADD CONSTRAINT "question_reports_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "user_stats" ADD CONSTRAINT "user_stats_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "audit_logs" ADD CONSTRAINT "audit_logs_admin_id_users_id_fk" FOREIGN KEY ("admin_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "user_question_log" ADD CONSTRAINT "user_question_log_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "user_question_log" ADD CONSTRAINT "user_question_log_question_bank_id_question_bank_id_fk" FOREIGN KEY ("question_bank_id") REFERENCES "public"."question_bank"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "email_verification_codes" ADD CONSTRAINT "email_verification_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "password_reset_tokens" ADD CONSTRAINT "password_reset_tokens_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;

src/db/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1772620981431,
+      "tag": "0000_fearless_salo",
+      "breakpoints": true
+    }
+  ]
+}

src/db/schema/auditLogs.ts

@@ -0,0 +1,18 @@
+import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';
+import { jsonb } from 'drizzle-orm/pg-core';
+import { users } from './users.js';
+
+export const auditLogs = pgTable('audit_logs', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  adminId: uuid('admin_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  action: varchar('action', { length: 100 }).notNull(),
+  targetType: varchar('target_type', { length: 50 }).notNull(),
+  targetId: uuid('target_id').notNull(),
+  details: jsonb('details').$type<Record<string, unknown>>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type AuditLog = typeof auditLogs.$inferSelect;
+export type NewAuditLog = typeof auditLogs.$inferInsert;

src/db/schema/enums.ts

@@ -0,0 +1,27 @@
+import { pgEnum } from 'drizzle-orm/pg-core';
+
+export const userRoleEnum = pgEnum('user_role', ['guest', 'free', 'pro', 'admin']);
+export const planEnum = pgEnum('plan', ['free', 'pro']);
+export const subscriptionStatusEnum = pgEnum('subscription_status', ['active', 'trialing', 'cancelled', 'expired']);
+export const stackEnum = pgEnum('stack', ['html', 'css', 'js', 'ts', 'react', 'vue', 'nodejs', 'git', 'web_basics']);
+export const levelEnum = pgEnum('level', ['basic', 'beginner', 'intermediate', 'advanced', 'expert']);
+export const testModeEnum = pgEnum('test_mode', ['fixed', 'infinite', 'marathon']);
+export const testStatusEnum = pgEnum('test_status', ['in_progress', 'completed', 'abandoned']);
+export const questionTypeEnum = pgEnum('question_type', ['single_choice', 'multiple_select', 'true_false', 'short_text']);
+export const questionStatusEnum = pgEnum('question_status', ['pending', 'approved', 'rejected']);
+export const questionSourceEnum = pgEnum('question_source', ['llm_generated', 'manual']);
+export const reportStatusEnum = pgEnum('report_status', ['open', 'resolved', 'dismissed']);
+export const selfLevelEnum = pgEnum('self_level', ['jun', 'mid', 'sen']);
+
+export type UserRole = (typeof userRoleEnum.enumValues)[number];
+export type Plan = (typeof planEnum.enumValues)[number];
+export type SubscriptionStatus = (typeof subscriptionStatusEnum.enumValues)[number];
+export type Stack = (typeof stackEnum.enumValues)[number];
+export type Level = (typeof levelEnum.enumValues)[number];
+export type TestMode = (typeof testModeEnum.enumValues)[number];
+export type TestStatus = (typeof testStatusEnum.enumValues)[number];
+export type QuestionType = (typeof questionTypeEnum.enumValues)[number];
+export type QuestionStatus = (typeof questionStatusEnum.enumValues)[number];
+export type QuestionSource = (typeof questionSourceEnum.enumValues)[number];
+export type ReportStatus = (typeof reportStatusEnum.enumValues)[number];
+export type SelfLevel = (typeof selfLevelEnum.enumValues)[number];

src/db/schema/index.ts

@@ -0,0 +1,13 @@
+export * from './enums.js';
+export * from './users.js';
+export * from './sessions.js';
+export * from './subscriptions.js';
+export * from './tests.js';
+export * from './testQuestions.js';
+export * from './questionBank.js';
+export * from './questionCacheMeta.js';
+export * from './questionReports.js';
+export * from './userStats.js';
+export * from './auditLogs.js';
+export * from './userQuestionLog.js';
+export * from './verificationTokens.js';

src/db/schema/questionBank.ts

@@ -0,0 +1,22 @@
+import { pgTable, uuid, text, integer, timestamp } from 'drizzle-orm/pg-core';
+import { jsonb } from 'drizzle-orm/pg-core';
+import { stackEnum, levelEnum, questionTypeEnum, questionStatusEnum, questionSourceEnum } from './enums.js';
+
+export const questionBank = pgTable('question_bank', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  stack: stackEnum('stack').notNull(),
+  level: levelEnum('level').notNull(),
+  type: questionTypeEnum('type').notNull(),
+  questionText: text('question_text').notNull(),
+  options: jsonb('options').$type<Array<{ key: string; text: string }>>(),
+  correctAnswer: jsonb('correct_answer').$type<string | string[]>().notNull(),
+  explanation: text('explanation').notNull(),
+  status: questionStatusEnum('status').notNull().default('pending'),
+  source: questionSourceEnum('source').notNull(),
+  usageCount: integer('usage_count').notNull().default(0),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  approvedAt: timestamp('approved_at', { withTimezone: true }),
+});
+
+export type QuestionBank = typeof questionBank.$inferSelect;
+export type NewQuestionBank = typeof questionBank.$inferInsert;

src/db/schema/questionCacheMeta.ts

@@ -0,0 +1,18 @@
+import { pgTable, uuid, varchar, integer, timestamp } from 'drizzle-orm/pg-core';
+import { jsonb } from 'drizzle-orm/pg-core';
+import { questionBank } from './questionBank.js';
+
+export const questionCacheMeta = pgTable('question_cache_meta', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  questionBankId: uuid('question_bank_id')
+    .notNull()
+    .references(() => questionBank.id, { onDelete: 'cascade' }),
+  llmModel: varchar('llm_model', { length: 100 }).notNull(),
+  promptHash: varchar('prompt_hash', { length: 64 }).notNull(),
+  generationTimeMs: integer('generation_time_ms').notNull(),
+  rawResponse: jsonb('raw_response').$type<unknown>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type QuestionCacheMeta = typeof questionCacheMeta.$inferSelect;
+export type NewQuestionCacheMeta = typeof questionCacheMeta.$inferInsert;

src/db/schema/questionReports.ts

@@ -0,0 +1,21 @@
+import { pgTable, uuid, text, timestamp } from 'drizzle-orm/pg-core';
+import { reportStatusEnum } from './enums.js';
+import { questionBank } from './questionBank.js';
+import { users } from './users.js';
+
+export const questionReports = pgTable('question_reports', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  questionBankId: uuid('question_bank_id')
+    .notNull()
+    .references(() => questionBank.id, { onDelete: 'cascade' }),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  reason: text('reason').notNull(),
+  status: reportStatusEnum('status').notNull().default('open'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  resolvedAt: timestamp('resolved_at', { withTimezone: true }),
+});
+
+export type QuestionReport = typeof questionReports.$inferSelect;
+export type NewQuestionReport = typeof questionReports.$inferInsert;

src/db/schema/sessions.ts

@@ -0,0 +1,18 @@
+import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';
+import { users } from './users.js';
+
+export const sessions = pgTable('sessions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  refreshTokenHash: varchar('refresh_token_hash', { length: 255 }).notNull(),
+  userAgent: varchar('user_agent', { length: 500 }),
+  ipAddress: varchar('ip_address', { length: 45 }),
+  lastActiveAt: timestamp('last_active_at', { withTimezone: true }).notNull().defaultNow(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type Session = typeof sessions.$inferSelect;
+export type NewSession = typeof sessions.$inferInsert;

src/db/schema/subscriptions.ts

@@ -0,0 +1,21 @@
+import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';
+import { planEnum, subscriptionStatusEnum } from './enums.js';
+import { users } from './users.js';
+
+export const subscriptions = pgTable('subscriptions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' })
+    .unique(),
+  plan: planEnum('plan').notNull(),
+  status: subscriptionStatusEnum('status').notNull(),
+  startedAt: timestamp('started_at', { withTimezone: true }).notNull(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }),
+  cancelledAt: timestamp('cancelled_at', { withTimezone: true }),
+  paymentProvider: varchar('payment_provider', { length: 50 }),
+  externalId: varchar('external_id', { length: 255 }),
+});
+
+export type Subscription = typeof subscriptions.$inferSelect;
+export type NewSubscription = typeof subscriptions.$inferInsert;

src/db/schema/testQuestions.ts

@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, integer, boolean, timestamp } from 'drizzle-orm/pg-core';
+import { jsonb } from 'drizzle-orm/pg-core';
+import { questionTypeEnum } from './enums.js';
+import { tests } from './tests.js';
+import { questionBank } from './questionBank.js';
+
+export const testQuestions = pgTable('test_questions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  testId: uuid('test_id')
+    .notNull()
+    .references(() => tests.id, { onDelete: 'cascade' }),
+  questionBankId: uuid('question_bank_id').references(() => questionBank.id, { onDelete: 'set null' }),
+  orderNumber: integer('order_number').notNull(),
+  type: questionTypeEnum('type').notNull(),
+  questionText: text('question_text').notNull(),
+  options: jsonb('options').$type<Array<{ key: string; text: string }>>(),
+  correctAnswer: jsonb('correct_answer').$type<string | string[]>().notNull(),
+  explanation: text('explanation').notNull(),
+  userAnswer: jsonb('user_answer').$type<string | string[]>(),
+  isCorrect: boolean('is_correct'),
+  answeredAt: timestamp('answered_at', { withTimezone: true }),
+});
+
+export type TestQuestion = typeof testQuestions.$inferSelect;
+export type NewTestQuestion = typeof testQuestions.$inferInsert;

src/db/schema/tests.ts

@@ -0,0 +1,22 @@
+import { pgTable, uuid, integer, timestamp } from 'drizzle-orm/pg-core';
+import { stackEnum, levelEnum, testModeEnum, testStatusEnum } from './enums.js';
+import { users } from './users.js';
+
+export const tests = pgTable('tests', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  stack: stackEnum('stack').notNull(),
+  level: levelEnum('level').notNull(),
+  questionCount: integer('question_count').notNull(),
+  mode: testModeEnum('mode').notNull().default('fixed'),
+  status: testStatusEnum('status').notNull().default('in_progress'),
+  score: integer('score'),
+  startedAt: timestamp('started_at', { withTimezone: true }).notNull().defaultNow(),
+  finishedAt: timestamp('finished_at', { withTimezone: true }),
+  timeLimitSeconds: integer('time_limit_seconds'),
+});
+
+export type Test = typeof tests.$inferSelect;
+export type NewTest = typeof tests.$inferInsert;

src/db/schema/userQuestionLog.ts

@@ -0,0 +1,17 @@
+import { pgTable, uuid, timestamp } from 'drizzle-orm/pg-core';
+import { users } from './users.js';
+import { questionBank } from './questionBank.js';
+
+export const userQuestionLog = pgTable('user_question_log', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  questionBankId: uuid('question_bank_id')
+    .notNull()
+    .references(() => questionBank.id, { onDelete: 'cascade' }),
+  seenAt: timestamp('seen_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type UserQuestionLog = typeof userQuestionLog.$inferSelect;
+export type NewUserQuestionLog = typeof userQuestionLog.$inferInsert;

src/db/schema/userStats.ts

@@ -0,0 +1,26 @@
+import { pgTable, uuid, integer, timestamp } from 'drizzle-orm/pg-core';
+import { unique } from 'drizzle-orm/pg-core';
+import { stackEnum, levelEnum } from './enums.js';
+import { users } from './users.js';
+
+export const userStats = pgTable(
+  'user_stats',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    userId: uuid('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    stack: stackEnum('stack').notNull(),
+    level: levelEnum('level').notNull(),
+    totalQuestions: integer('total_questions').notNull().default(0),
+    correctAnswers: integer('correct_answers').notNull().default(0),
+    testsTaken: integer('tests_taken').notNull().default(0),
+    lastTestAt: timestamp('last_test_at', { withTimezone: true }),
+  },
+  (t) => ({
+    userStackLevelUnique: unique().on(t.userId, t.stack, t.level),
+  })
+);
+
+export type UserStat = typeof userStats.$inferSelect;
+export type NewUserStat = typeof userStats.$inferInsert;

src/db/schema/users.ts

@@ -0,0 +1,21 @@
+import { pgTable, uuid, varchar, timestamp, boolean } from 'drizzle-orm/pg-core';
+import { userRoleEnum, selfLevelEnum } from './enums.js';
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  passwordHash: varchar('password_hash', { length: 255 }).notNull(),
+  nickname: varchar('nickname', { length: 30 }).notNull(),
+  avatarUrl: varchar('avatar_url', { length: 500 }),
+  country: varchar('country', { length: 100 }),
+  city: varchar('city', { length: 100 }),
+  selfLevel: selfLevelEnum('self_level'),
+  isPublic: boolean('is_public').notNull().default(true),
+  role: userRoleEnum('role').notNull().default('free'),
+  emailVerifiedAt: timestamp('email_verified_at', { withTimezone: true }),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;

src/db/schema/verificationTokens.ts

@@ -0,0 +1,22 @@
+import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';
+import { users } from './users.js';
+
+export const emailVerificationCodes = pgTable('email_verification_codes', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  code: varchar('code', { length: 10 }).notNull(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const passwordResetTokens = pgTable('password_reset_tokens', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  tokenHash: varchar('token_hash', { length: 255 }).notNull(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});

src/db/seed.ts

@@ -0,0 +1,47 @@
+import 'dotenv/config';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { eq } from 'drizzle-orm';
+import pg from 'pg';
+import argon2 from 'argon2';
+import { env } from '../config/env.js';
+import { users } from './schema/index.js';
+
+const { Pool } = pg;
+
+const TEST_USER = {
+  email: 'test@example.com',
+  password: 'TestPassword123!',
+  nickname: 'TestUser',
+};
+
+async function runSeed() {
+  const pool = new Pool({ connectionString: env.DATABASE_URL });
+  const db = drizzle(pool);
+
+  if (env.NODE_ENV !== 'development') {
+    await pool.end();
+    return;
+  }
+
+  const existing = await db.select().from(users).where(eq(users.email, TEST_USER.email)).limit(1);
+  if (existing.length > 0) {
+    await pool.end();
+    return;
+  }
+
+  const passwordHash = await argon2.hash(TEST_USER.password);
+  await db.insert(users).values({
+    email: TEST_USER.email,
+    passwordHash,
+    nickname: TEST_USER.nickname,
+    role: 'free',
+    emailVerifiedAt: new Date(),
+  });
+
+  await pool.end();
+}
+
+runSeed().catch((err) => {
+  console.error('Seed failed:', err);
+  process.exit(1);
+});

src/plugins/auth.ts

@@ -0,0 +1,58 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import fp from 'fastify-plugin';
+import { eq } from 'drizzle-orm';
+import { verifyToken, isAccessPayload } from '../utils/jwt.js';
+import { unauthorized, forbidden } from '../utils/errors.js';
+import { users } from '../db/schema/users.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    authenticate: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    authenticateAdmin: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+  interface FastifyRequest {
+    user?: { id: string; email: string };
+  }
+}
+
+export async function authenticate(req: FastifyRequest, _reply: FastifyReply): Promise<void> {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    throw unauthorized('Missing or invalid authorization header');
+  }
+
+  const token = authHeader.slice(7);
+
+  try {
+    const payload = await verifyToken(token);
+
+    if (!isAccessPayload(payload)) {
+      throw unauthorized('Invalid token type');
+    }
+
+    req.user = { id: payload.sub, email: payload.email };
+  } catch {
+    throw unauthorized('Invalid or expired token');
+  }
+}
+
+export async function authenticateAdmin(req: FastifyRequest, _reply: FastifyReply): Promise<void> {
+  if (!req.user) {
+    throw unauthorized('Authentication required');
+  }
+
+  const [user] = await req.server.db.select({ role: users.role }).from(users).where(eq(users.id, req.user.id));
+
+  if (!user || user.role !== 'admin') {
+    throw forbidden('Admin access required');
+  }
+}
+
+const authPlugin = async (app: FastifyInstance) => {
+  app.decorateRequest('user', undefined);
+  app.decorate('authenticate', authenticate);
+  app.decorate('authenticateAdmin', authenticateAdmin);
+};
+
+export default fp(authPlugin, { name: 'auth', dependencies: ['database'] });

src/plugins/database.ts

@@ -0,0 +1,33 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+import * as schema from '../db/schema/index.js';
+
+const { Pool } = pg;
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    db: ReturnType<typeof drizzle<typeof schema>>;
+  }
+}
+
+const databasePlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const pool = new Pool({
+    connectionString: env.DATABASE_URL,
+    max: 10,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 5000,
+  });
+
+  const db = drizzle(pool, { schema });
+
+  app.decorate('db', db);
+
+  app.addHook('onClose', async () => {
+    await pool.end();
+  });
+};
+
+export default fp(databasePlugin, { name: 'database' });

src/plugins/rateLimit.ts

@@ -0,0 +1,58 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import rateLimit from '@fastify/rate-limit';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    rateLimitOptions: {
+      register: { max: number; timeWindow: string };
+      forgotPassword: { max: number; timeWindow: string };
+      verifyEmail: { max: number; timeWindow: string };
+      apiAuthed: { max: number; timeWindow: string };
+      apiGuest: { max: number; timeWindow: string };
+    };
+  }
+}
+
+const rateLimitPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const options = {
+    register: { max: env.RATE_LIMIT_REGISTER, timeWindow: '1 hour' },
+    forgotPassword: { max: env.RATE_LIMIT_FORGOT_PASSWORD, timeWindow: '1 hour' },
+    verifyEmail: { max: env.RATE_LIMIT_VERIFY_EMAIL, timeWindow: '15 minutes' },
+    apiAuthed: { max: env.RATE_LIMIT_API_AUTHED, timeWindow: '1 minute' },
+    apiGuest: { max: env.RATE_LIMIT_API_GUEST, timeWindow: '1 minute' },
+  };
+
+  app.decorate('rateLimitOptions', options);
+
+  await app.register(rateLimit, {
+    global: false,
+    max: options.apiGuest.max,
+    timeWindow: options.apiGuest.timeWindow,
+    keyGenerator: (req) => {
+      return (req.ip ?? 'unknown') as string;
+    },
+    redis: app.redis,
+    addHeadersOnExceeding: {
+      'x-ratelimit-limit': true,
+      'x-ratelimit-remaining': true,
+      'x-ratelimit-reset': true,
+    },
+    addHeaders: {
+      'x-ratelimit-limit': true,
+      'x-ratelimit-remaining': true,
+      'x-ratelimit-reset': true,
+      'retry-after': true,
+    },
+    errorResponseBuilder: (_req, context) => ({
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Too many requests, please try again later',
+        retryAfter: context.ttl,
+      },
+    }),
+  });
+};
+
+export default fp(rateLimitPlugin, { name: 'rateLimit', dependencies: ['redis'] });

src/plugins/redis.ts

@@ -0,0 +1,32 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { Redis } from 'ioredis';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    redis: Redis;
+  }
+}
+
+const redisPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const redis = new Redis(env.REDIS_URL, {
+    maxRetriesPerRequest: 3,
+    retryStrategy(times: number) {
+      const delay = Math.min(times * 100, 3000);
+      return delay;
+    },
+  });
+
+  redis.on('error', (err: Error) => {
+    app.log.error({ err }, 'Redis connection error');
+  });
+
+  app.decorate('redis', redis);
+
+  app.addHook('onClose', async () => {
+    await redis.quit();
+  });
+};
+
+export default fp(redisPlugin, { name: 'redis' });

src/plugins/security.ts

@@ -0,0 +1,21 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import helmet from '@fastify/helmet';
+import cors from '@fastify/cors';
+import fp from 'fastify-plugin';
+import { getCorsOrigins } from '../config/env.js';
+
+const securityPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  await app.register(helmet, {
+    contentSecurityPolicy: false,
+    crossOriginEmbedderPolicy: false,
+  });
+
+  await app.register(cors, {
+    origin: getCorsOrigins(),
+    credentials: true,
+    methods: ['GET', 'POST', 'PATCH', 'DELETE', 'PUT', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+  });
+};
+
+export default fp(securityPlugin, { name: 'security' });

src/plugins/subscription.ts

@@ -0,0 +1,71 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import fp from 'fastify-plugin';
+import { eq } from 'drizzle-orm';
+import { subscriptions } from '../db/schema/subscriptions.js';
+import { forbidden } from '../utils/errors.js';
+
+export type SubscriptionInfo = {
+  plan: 'free' | 'pro';
+  status: 'active' | 'trialing' | 'cancelled' | 'expired';
+  isPro: boolean;
+  expiresAt: Date | null;
+};
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    subscription?: SubscriptionInfo | null;
+  }
+  interface FastifyInstance {
+    withSubscription: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    requirePro: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+}
+
+async function loadSubscription(db: FastifyInstance['db'], userId: string): Promise<SubscriptionInfo | null> {
+  const [sub] = await db
+    .select()
+    .from(subscriptions)
+    .where(eq(subscriptions.userId, userId))
+    .limit(1);
+
+  if (!sub) return null;
+
+  const now = new Date();
+  const isExpired = sub.expiresAt && sub.expiresAt < now;
+  const isPro =
+    sub.plan === 'pro' &&
+    (sub.status === 'active' || sub.status === 'trialing') &&
+    !isExpired;
+
+  return {
+    plan: sub.plan as 'free' | 'pro',
+    status: sub.status as SubscriptionInfo['status'],
+    isPro,
+    expiresAt: sub.expiresAt,
+  };
+}
+
+export async function requirePro(req: FastifyRequest, _reply: FastifyReply): Promise<void> {
+  const sub = req.subscription;
+
+  if (!sub?.isPro) {
+    throw forbidden('Pro subscription required');
+  }
+}
+
+const subscriptionPlugin = async (app: FastifyInstance) => {
+  app.decorateRequest('subscription', undefined);
+
+  app.decorate('withSubscription', async (req: FastifyRequest, _reply: FastifyReply) => {
+    if (!req.user?.id) return;
+    const sub = await loadSubscription(app.db, req.user.id);
+    req.subscription = sub;
+  });
+
+  app.decorate('requirePro', requirePro);
+};
+
+export default fp(subscriptionPlugin, {
+  name: 'subscription',
+  dependencies: ['database', 'auth'],
+});

src/routes/admin/questions.ts

@@ -0,0 +1,131 @@
+import type { FastifyInstance } from 'fastify';
+import { AdminQuestionService } from '../../services/admin/admin-question.service.js';
+import type { EditQuestionInput } from '../../services/admin/admin-question.service.js';
+
+const STACKS = ['html', 'css', 'js', 'ts', 'react', 'vue', 'nodejs', 'git', 'web_basics'] as const;
+const LEVELS = ['basic', 'beginner', 'intermediate', 'advanced', 'expert'] as const;
+const QUESTION_TYPES = ['single_choice', 'multiple_select', 'true_false', 'short_text'] as const;
+
+const listPendingQuerySchema = {
+  querystring: {
+    type: 'object',
+    properties: {
+      limit: { type: 'integer', minimum: 1, maximum: 100 },
+      offset: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+};
+
+const questionIdParamsSchema = {
+  params: {
+    type: 'object',
+    required: ['questionId'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+    },
+  },
+};
+
+const editQuestionSchema = {
+  params: {
+    type: 'object',
+    required: ['questionId'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+    },
+  },
+  body: {
+    type: 'object',
+    properties: {
+      stack: { type: 'string', enum: [...STACKS] },
+      level: { type: 'string', enum: [...LEVELS] },
+      type: { type: 'string', enum: [...QUESTION_TYPES] },
+      questionText: { type: 'string', minLength: 1 },
+      options: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['key', 'text'],
+          properties: {
+            key: { type: 'string' },
+            text: { type: 'string' },
+          },
+        },
+      },
+      correctAnswer: {
+        oneOf: [
+          { type: 'string' },
+          { type: 'array', items: { type: 'string' } },
+        ],
+      },
+      explanation: { type: 'string', minLength: 1 },
+    },
+    additionalProperties: false,
+  },
+};
+
+export async function adminQuestionsRoutes(app: FastifyInstance) {
+  const adminQuestionService = new AdminQuestionService(app.db);
+  const { rateLimitOptions } = app;
+
+  app.get(
+    '/questions/pending',
+    {
+      schema: listPendingQuerySchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const { limit, offset } = (req.query as { limit?: number; offset?: number }) ?? {};
+      const result = await adminQuestionService.listPending(limit, offset);
+      return reply.send(result);
+    },
+  );
+
+  app.post(
+    '/questions/:questionId/approve',
+    {
+      schema: questionIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      await adminQuestionService.approve(questionId, adminId);
+      return reply.status(204).send();
+    },
+  );
+
+  app.post(
+    '/questions/:questionId/reject',
+    {
+      schema: questionIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      await adminQuestionService.reject(questionId, adminId);
+      return reply.status(204).send();
+    },
+  );
+
+  app.patch(
+    '/questions/:questionId',
+    {
+      schema: editQuestionSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.authenticateAdmin],
+    },
+    async (req, reply) => {
+      const adminId = req.user!.id;
+      const { questionId } = req.params as { questionId: string };
+      const body = req.body as EditQuestionInput;
+      const question = await adminQuestionService.edit(questionId, body, adminId);
+      return reply.send(question);
+    },
+  );
+}

src/routes/auth.ts

@@ -0,0 +1,192 @@
+import type { FastifyInstance } from 'fastify';
+import { AuthService } from '../services/auth/auth.service.js';
+import { checkBlocked, clearOnSuccess, recordFailedAttempt } from '../utils/loginLockout.js';
+
+const registerSchema = {
+  body: {
+    type: 'object',
+    required: ['email', 'password', 'nickname'],
+    properties: {
+      email: { type: 'string', minLength: 1 },
+      password: { type: 'string', minLength: 8 },
+      nickname: { type: 'string', minLength: 2, maxLength: 30 },
+    },
+  },
+};
+
+const loginSchema = {
+  body: {
+    type: 'object',
+    required: ['email', 'password'],
+    properties: {
+      email: { type: 'string', minLength: 1 },
+      password: { type: 'string' },
+    },
+  },
+};
+
+const refreshTokenSchema = {
+  body: {
+    type: 'object',
+    required: ['refreshToken'],
+    properties: {
+      refreshToken: { type: 'string' },
+    },
+  },
+};
+
+const logoutSchema = refreshTokenSchema;
+
+const verifyEmailSchema = {
+  body: {
+    type: 'object',
+    required: ['userId', 'code'],
+    properties: {
+      userId: { type: 'string', minLength: 1 },
+      code: { type: 'string', minLength: 1, maxLength: 10 },
+    },
+  },
+};
+
+const forgotPasswordSchema = {
+  body: {
+    type: 'object',
+    required: ['email'],
+    properties: {
+      email: { type: 'string', minLength: 1 },
+    },
+  },
+};
+
+const resetPasswordSchema = {
+  body: {
+    type: 'object',
+    required: ['token', 'newPassword'],
+    properties: {
+      token: { type: 'string' },
+      newPassword: { type: 'string', minLength: 8 },
+    },
+  },
+};
+
+export async function authRoutes(app: FastifyInstance) {
+  const authService = new AuthService(app.db);
+  const { rateLimitOptions } = app;
+
+  app.post(
+    '/register',
+    { schema: registerSchema, config: { rateLimit: rateLimitOptions.register } },
+    async (req, reply) => {
+      const body = req.body as { email: string; password: string; nickname: string };
+      const { userId, verificationCode } = await authService.register(body);
+
+      return reply.status(201).send({
+        userId,
+        message: 'Registration successful. Please verify your email.',
+        verificationCode,
+      });
+    },
+  );
+
+  app.post(
+    '/login',
+    {
+      schema: loginSchema,
+      preValidation: async (req, reply) => {
+        const ip = req.ip ?? 'unknown';
+        const { blocked, retryAfter } = await checkBlocked(app.redis, ip);
+        if (blocked) {
+          if (retryAfter !== undefined) {
+            reply.header('Retry-After', String(retryAfter));
+          }
+          return reply.status(429).send({
+            error: {
+              code: 'RATE_LIMIT_EXCEEDED',
+              message: 'Too many failed login attempts. Please try again later.',
+              retryAfter,
+            },
+          });
+        }
+      },
+    },
+    async (req, reply) => {
+      const body = req.body as { email: string; password: string };
+      const userAgent = req.headers['user-agent'];
+      const ip = req.ip ?? 'unknown';
+
+      try {
+        const result = await authService.login({
+          email: body.email,
+          password: body.password,
+          userAgent,
+          ipAddress: ip,
+        });
+        await clearOnSuccess(app.redis, ip);
+        return reply.send(result);
+      } catch (err) {
+        await recordFailedAttempt(app.redis, ip);
+        throw err;
+      }
+    },
+  );
+
+  app.post(
+    '/logout',
+    { schema: logoutSchema, config: { rateLimit: rateLimitOptions.apiGuest } },
+    async (req, reply) => {
+      const body = req.body as { refreshToken: string };
+      await authService.logout(body.refreshToken);
+      return reply.status(204).send();
+    },
+  );
+
+  app.post(
+    '/refresh',
+    { schema: refreshTokenSchema, config: { rateLimit: rateLimitOptions.apiGuest } },
+    async (req, reply) => {
+      const body = req.body as { refreshToken: string };
+      const userAgent = req.headers['user-agent'];
+      const ipAddress = req.ip;
+
+      const result = await authService.refresh({
+        refreshToken: body.refreshToken,
+        userAgent,
+        ipAddress,
+      });
+
+      return reply.send(result);
+    },
+  );
+
+  app.post(
+    '/verify-email',
+    { schema: verifyEmailSchema, config: { rateLimit: rateLimitOptions.verifyEmail } },
+    async (req, reply) => {
+      const body = req.body as { userId: string; code: string };
+      await authService.verifyEmail(body.userId, body.code);
+      return reply.send({ message: 'Email verified successfully' });
+    },
+  );
+
+  app.post(
+    '/forgot-password',
+    { schema: forgotPasswordSchema, config: { rateLimit: rateLimitOptions.forgotPassword } },
+    async (req, reply) => {
+      const body = req.body as { email: string };
+      await authService.forgotPassword(body.email);
+      return reply.send({
+        message: 'If the email exists, a reset link has been sent.',
+      });
+    },
+  );
+
+  app.post(
+    '/reset-password',
+    { schema: resetPasswordSchema, config: { rateLimit: rateLimitOptions.forgotPassword } },
+    async (req, reply) => {
+      const body = req.body as { token: string; newPassword: string };
+      await authService.resetPassword(body.token, body.newPassword);
+      return reply.send({ message: 'Password reset successfully' });
+    },
+  );
+}

src/routes/profile.ts

@@ -0,0 +1,73 @@
+import type { FastifyInstance } from 'fastify';
+import { UserService } from '../services/user/user.service.js';
+
+const patchProfileSchema = {
+  body: {
+    type: 'object',
+    properties: {
+      nickname: { type: 'string', minLength: 2, maxLength: 30 },
+      avatarUrl: { type: ['string', 'null'], maxLength: 500 },
+      country: { type: ['string', 'null'], maxLength: 100 },
+      city: { type: ['string', 'null'], maxLength: 100 },
+      selfLevel: { type: ['string', 'null'], enum: ['jun', 'mid', 'sen'] },
+      isPublic: { type: 'boolean' },
+    },
+    additionalProperties: false,
+  },
+};
+
+const usernameParamsSchema = {
+  params: {
+    type: 'object',
+    required: ['username'],
+    properties: {
+      username: { type: 'string', minLength: 2, maxLength: 30 },
+    },
+  },
+};
+
+export async function profileRoutes(app: FastifyInstance) {
+  const userService = new UserService(app.db);
+  const { rateLimitOptions } = app;
+
+  app.get(
+    '/',
+    {
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.withSubscription],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const profile = await userService.getPrivateProfile(userId);
+      return reply.send(profile);
+    },
+  );
+
+  app.patch(
+    '/',
+    {
+      schema: patchProfileSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const body = req.body as Parameters<UserService['updateProfile']>[1];
+      const profile = await userService.updateProfile(userId, body);
+      return reply.send(profile);
+    },
+  );
+
+  app.get(
+    '/:username',
+    {
+      schema: usernameParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiGuest },
+    },
+    async (req, reply) => {
+      const { username } = req.params as { username: string };
+      const profile = await userService.getPublicProfile(username);
+      return reply.send(profile);
+    },
+  );
+}

src/routes/tests.ts

@@ -0,0 +1,185 @@
+import type { FastifyInstance } from 'fastify';
+import { LlmService } from '../services/llm/llm.service.js';
+import { QuestionService } from '../services/questions/question.service.js';
+import { TestsService } from '../services/tests/tests.service.js';
+import { notFound } from '../utils/errors.js';
+import type { CreateTestInput } from '../services/tests/tests.service.js';
+import type { TestSnapshot } from '../services/tests/tests.service.js';
+
+const STACKS = ['html', 'css', 'js', 'ts', 'react', 'vue', 'nodejs', 'git', 'web_basics'] as const;
+const LEVELS = ['basic', 'beginner', 'intermediate', 'advanced', 'expert'] as const;
+
+const createTestSchema = {
+  body: {
+    type: 'object',
+    required: ['stack', 'level', 'questionCount'],
+    properties: {
+      stack: { type: 'string', enum: STACKS },
+      level: { type: 'string', enum: LEVELS },
+      questionCount: { type: 'integer', minimum: 1, maximum: 50 },
+      mode: { type: 'string', enum: ['fixed', 'infinite', 'marathon'] },
+    },
+    additionalProperties: false,
+  },
+};
+
+const testIdParamsSchema = {
+  params: {
+    type: 'object',
+    required: ['testId'],
+    properties: {
+      testId: { type: 'string', format: 'uuid' },
+    },
+  },
+};
+
+const answerSchema = {
+  params: {
+    type: 'object',
+    required: ['testId'],
+    properties: {
+      testId: { type: 'string', format: 'uuid' },
+    },
+  },
+  body: {
+    type: 'object',
+    required: ['questionId', 'answer'],
+    properties: {
+      questionId: { type: 'string', format: 'uuid' },
+      answer: {
+        oneOf: [
+          { type: 'string' },
+          { type: 'array', items: { type: 'string' } },
+        ],
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+const historyQuerySchema = {
+  querystring: {
+    type: 'object',
+    properties: {
+      limit: { type: 'integer', minimum: 1, maximum: 100 },
+      offset: { type: 'integer', minimum: 0 },
+    },
+    additionalProperties: false,
+  },
+};
+
+function stripAnswersForClient(
+  q: TestSnapshot
+): Omit<TestSnapshot, 'correctAnswer' | 'explanation'> {
+  const { correctAnswer: _, explanation: __, ...rest } = q;
+  return rest;
+}
+
+export async function testsRoutes(app: FastifyInstance) {
+  const llmService = new LlmService();
+  const questionService = new QuestionService(app.db, llmService);
+  const testsService = new TestsService(app.db, questionService);
+  const { rateLimitOptions } = app;
+
+  app.get(
+    '/',
+    {
+      schema: historyQuerySchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { limit, offset } = (req.query as { limit?: number; offset?: number }) ?? {};
+      const { tests: testList, total } = await testsService.getHistory(
+        userId,
+        { limit, offset }
+      );
+      return reply.send({ tests: testList, total });
+    }
+  );
+
+  app.post(
+    '/',
+    {
+      schema: createTestSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate, app.withSubscription],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const body = req.body as CreateTestInput;
+      const test = await testsService.createTest(userId, body);
+      const hideAnswers = test.status === 'in_progress';
+      const response = {
+        ...test,
+        questions: hideAnswers
+          ? test.questions.map(stripAnswersForClient)
+          : test.questions,
+      };
+      return reply.status(201).send(response);
+    }
+  );
+
+  app.post(
+    '/:testId/answer',
+    {
+      schema: answerSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const { questionId, answer } = req.body as { questionId: string; answer: string | string[] };
+      const snapshot = await testsService.answerQuestion(
+        userId,
+        testId,
+        questionId,
+        answer
+      );
+      return reply.send(snapshot);
+    }
+  );
+
+  app.post(
+    '/:testId/finish',
+    {
+      schema: testIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const test = await testsService.finishTest(userId, testId);
+      return reply.send(test);
+    }
+  );
+
+  app.get(
+    '/:testId',
+    {
+      schema: testIdParamsSchema,
+      config: { rateLimit: rateLimitOptions.apiAuthed },
+      preHandler: [app.authenticate],
+    },
+    async (req, reply) => {
+      const userId = req.user!.id;
+      const { testId } = req.params as { testId: string };
+      const test = await testsService.getById(userId, testId);
+      if (!test) {
+        throw notFound('Test not found');
+      }
+      const hideAnswers = test.status === 'in_progress';
+      const response = {
+        ...test,
+        questions: hideAnswers
+          ? test.questions.map(stripAnswersForClient)
+          : test.questions,
+      };
+      return reply.send(response);
+    }
+  );
+
+}

src/server.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { buildApp } from './app.js';
+import { env } from './config/env.js';
+
+async function main() {
+  const app = await buildApp();
+
+  try {
+    await app.listen({ port: env.PORT, host: env.HOST });
+    app.log.info({ port: env.PORT }, 'Server started');
+  } catch (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+
+  const shutdown = async () => {
+    app.log.info('Shutting down...');
+    await app.close();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main();

src/services/admin/admin-question.service.ts

@@ -0,0 +1,194 @@
+import { eq, asc, count } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { questionBank, auditLogs } from '../../db/schema/index.js';
+import { notFound } from '../../utils/errors.js';
+import type { Stack, Level, QuestionType } from '../../db/schema/enums.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type PendingQuestion = {
+  id: string;
+  stack: Stack;
+  level: Level;
+  type: QuestionType;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+  source: string;
+  createdAt: Date;
+};
+
+export type EditQuestionInput = {
+  stack?: Stack;
+  level?: Level;
+  type?: QuestionType;
+  questionText?: string;
+  options?: Array<{ key: string; text: string }> | null;
+  correctAnswer?: string | string[];
+  explanation?: string;
+};
+
+export type ListPendingResult = {
+  questions: PendingQuestion[];
+  total: number;
+};
+
+export class AdminQuestionService {
+  constructor(private readonly db: Db) {}
+
+  async listPending(limit = 50, offset = 0): Promise<ListPendingResult> {
+    const questions = await this.db
+      .select({
+        id: questionBank.id,
+        stack: questionBank.stack,
+        level: questionBank.level,
+        type: questionBank.type,
+        questionText: questionBank.questionText,
+        options: questionBank.options,
+        correctAnswer: questionBank.correctAnswer,
+        explanation: questionBank.explanation,
+        source: questionBank.source,
+        createdAt: questionBank.createdAt,
+      })
+      .from(questionBank)
+      .where(eq(questionBank.status, 'pending'))
+      .orderBy(asc(questionBank.createdAt))
+      .limit(limit)
+      .offset(offset);
+
+    const [{ count: totalCount }] = await this.db
+      .select({ count: count() })
+      .from(questionBank)
+      .where(eq(questionBank.status, 'pending'));
+
+    return {
+      questions: questions.map((q) => ({
+        id: q.id,
+        stack: q.stack,
+        level: q.level,
+        type: q.type,
+        questionText: q.questionText,
+        options: q.options,
+        correctAnswer: q.correctAnswer,
+        explanation: q.explanation,
+        source: q.source,
+        createdAt: q.createdAt,
+      })),
+      total: totalCount ?? 0,
+    };
+  }
+
+  async approve(questionId: string, adminId: string): Promise<void> {
+    const [updated] = await this.db
+      .update(questionBank)
+      .set({
+        status: 'approved',
+        approvedAt: new Date(),
+      })
+      .where(eq(questionBank.id, questionId))
+      .returning({ id: questionBank.id });
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_approved',
+      targetType: 'question',
+      targetId: questionId,
+    });
+  }
+
+  async reject(questionId: string, adminId: string): Promise<void> {
+    const [updated] = await this.db
+      .update(questionBank)
+      .set({ status: 'rejected' })
+      .where(eq(questionBank.id, questionId))
+      .returning({ id: questionBank.id });
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_rejected',
+      targetType: 'question',
+      targetId: questionId,
+    });
+  }
+
+  async edit(questionId: string, input: EditQuestionInput, adminId: string): Promise<PendingQuestion> {
+    const updates: Partial<{
+      stack: Stack;
+      level: Level;
+      type: QuestionType;
+      questionText: string;
+      options: Array<{ key: string; text: string }> | null;
+      correctAnswer: string | string[];
+      explanation: string;
+    }> = {};
+
+    if (input.stack !== undefined) updates.stack = input.stack;
+    if (input.level !== undefined) updates.level = input.level;
+    if (input.type !== undefined) updates.type = input.type;
+    if (input.questionText !== undefined) updates.questionText = input.questionText;
+    if (input.options !== undefined) updates.options = input.options;
+    if (input.correctAnswer !== undefined) updates.correctAnswer = input.correctAnswer;
+    if (input.explanation !== undefined) updates.explanation = input.explanation;
+
+    if (Object.keys(updates).length === 0) {
+      const [existing] = await this.db
+        .select()
+        .from(questionBank)
+        .where(eq(questionBank.id, questionId));
+      if (!existing) throw notFound('Question not found');
+      return {
+        id: existing.id,
+        stack: existing.stack,
+        level: existing.level,
+        type: existing.type,
+        questionText: existing.questionText,
+        options: existing.options,
+        correctAnswer: existing.correctAnswer,
+        explanation: existing.explanation,
+        source: existing.source,
+        createdAt: existing.createdAt,
+      };
+    }
+
+    const [updated] = await this.db
+      .update(questionBank)
+      .set(updates)
+      .where(eq(questionBank.id, questionId))
+      .returning();
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    await this.db.insert(auditLogs).values({
+      adminId,
+      action: 'question_edited',
+      targetType: 'question',
+      targetId: questionId,
+      details: updates as Record<string, unknown>,
+    });
+
+    return {
+      id: updated.id,
+      stack: updated.stack,
+      level: updated.level,
+      type: updated.type,
+      questionText: updated.questionText,
+      options: updated.options,
+      correctAnswer: updated.correctAnswer,
+      explanation: updated.explanation,
+      source: updated.source,
+      createdAt: updated.createdAt,
+    };
+  }
+}

src/services/auth/auth.service.ts

@@ -0,0 +1,304 @@
+import { eq, and, gt } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { users, sessions, emailVerificationCodes, passwordResetTokens } from '../../db/schema/index.js';
+import { hashPassword, verifyPassword } from '../../utils/password.js';
+import {
+  signAccessToken,
+  signRefreshToken,
+  verifyToken,
+  isRefreshPayload,
+  hashToken,
+} from '../../utils/jwt.js';
+import {
+  AppError,
+  conflict,
+  unauthorized,
+  notFound,
+  ERROR_CODES,
+} from '../../utils/errors.js';
+import { randomBytes, randomUUID } from 'node:crypto';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export interface RegisterInput {
+  email: string;
+  password: string;
+  nickname: string;
+}
+
+export interface LoginInput {
+  email: string;
+  password: string;
+  userAgent?: string;
+  ipAddress?: string;
+}
+
+export interface LoginResult {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+}
+
+export interface RefreshInput {
+  refreshToken: string;
+  userAgent?: string;
+  ipAddress?: string;
+}
+
+export interface ForgotPasswordResult {
+  token: string;
+  expiresAt: Date;
+}
+
+const REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const VERIFICATION_CODE_LENGTH = 6;
+const VERIFICATION_CODE_TTL_MS = 15 * 60 * 1000;
+const RESET_TOKEN_TTL_MS = 60 * 60 * 1000;
+
+export class AuthService {
+  constructor(private readonly db: Db) {}
+
+  async register(input: RegisterInput): Promise<{ userId: string; verificationCode: string }> {
+    const [existing] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.email, input.email.toLowerCase().trim()))
+      .limit(1);
+
+    if (existing) {
+      throw conflict(ERROR_CODES.EMAIL_TAKEN, 'Email already registered');
+    }
+
+    const [nicknameConflict] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.nickname, input.nickname.trim()))
+      .limit(1);
+
+    if (nicknameConflict) {
+      throw conflict(ERROR_CODES.NICKNAME_TAKEN, 'Nickname already taken');
+    }
+
+    const passwordHash = await hashPassword(input.password);
+
+    const [user] = await this.db
+      .insert(users)
+      .values({
+        email: input.email.toLowerCase().trim(),
+        passwordHash,
+        nickname: input.nickname.trim(),
+      })
+      .returning({ id: users.id });
+
+    if (!user) {
+      throw new AppError(ERROR_CODES.INTERNAL_ERROR, 'Failed to create user', 500);
+    }
+
+    const code = randomBytes(VERIFICATION_CODE_LENGTH)
+      .toString('hex')
+      .slice(0, VERIFICATION_CODE_LENGTH)
+      .toUpperCase();
+    const expiresAt = new Date(Date.now() + VERIFICATION_CODE_TTL_MS);
+
+    await this.db.insert(emailVerificationCodes).values({
+      userId: user.id,
+      code,
+      expiresAt,
+    });
+
+    return { userId: user.id, verificationCode: code };
+  }
+
+  async login(input: LoginInput): Promise<LoginResult> {
+    const [user] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.email, input.email.toLowerCase().trim()))
+      .limit(1);
+
+    if (!user || !(await verifyPassword(user.passwordHash, input.password))) {
+      throw unauthorized('Invalid email or password');
+    }
+
+    const [accessToken, refreshToken] = await Promise.all([
+      signAccessToken({ sub: user.id, email: user.email }),
+      signRefreshToken({ sub: user.id, sid: randomUUID() }),
+    ]);
+
+    const refreshHash = hashToken(refreshToken);
+    const expiresAt = new Date(Date.now() + REFRESH_TTL_MS);
+
+    await this.db.insert(sessions).values({
+      userId: user.id,
+      refreshTokenHash: refreshHash,
+      userAgent: input.userAgent ?? null,
+      ipAddress: input.ipAddress ?? null,
+      expiresAt,
+    });
+
+    return {
+      accessToken,
+      refreshToken,
+      expiresIn: Math.floor(REFRESH_TTL_MS / 1000),
+    };
+  }
+
+  async logout(refreshToken: string): Promise<void> {
+    const hash = hashToken(refreshToken);
+    await this.db.delete(sessions).where(eq(sessions.refreshTokenHash, hash));
+  }
+
+  async refresh(input: RefreshInput): Promise<LoginResult> {
+    const payload = await verifyToken(input.refreshToken);
+
+    if (!isRefreshPayload(payload)) {
+      throw unauthorized('Invalid refresh token');
+    }
+
+    const hash = hashToken(input.refreshToken);
+
+    const [session] = await this.db
+      .select()
+      .from(sessions)
+      .where(and(eq(sessions.refreshTokenHash, hash), gt(sessions.expiresAt, new Date())))
+      .limit(1);
+
+    if (!session) {
+      throw new AppError(ERROR_CODES.INVALID_REFRESH_TOKEN, 'Invalid or expired refresh token', 401);
+    }
+
+    await this.db.delete(sessions).where(eq(sessions.id, session.id));
+
+    const [user] = await this.db.select().from(users).where(eq(users.id, session.userId)).limit(1);
+
+    if (!user) {
+      throw notFound('User not found');
+    }
+
+    const [accessToken, newRefreshToken] = await Promise.all([
+      signAccessToken({ sub: user.id, email: user.email }),
+      signRefreshToken({ sub: user.id, sid: randomUUID() }),
+    ]);
+
+    const newHash = hashToken(newRefreshToken);
+    const expiresAt = new Date(Date.now() + REFRESH_TTL_MS);
+
+    await this.db.insert(sessions).values({
+      userId: user.id,
+      refreshTokenHash: newHash,
+      userAgent: input.userAgent ?? session.userAgent,
+      ipAddress: input.ipAddress ?? session.ipAddress,
+      expiresAt,
+    });
+
+    return {
+      accessToken,
+      refreshToken: newRefreshToken,
+      expiresIn: Math.floor(REFRESH_TTL_MS / 1000),
+    };
+  }
+
+  async verifyEmail(userId: string, verificationCode: string): Promise<void> {
+    const codeUpper = verificationCode.toUpperCase();
+    const [record] = await this.db
+      .select()
+      .from(emailVerificationCodes)
+      .where(
+        and(
+          eq(emailVerificationCodes.userId, userId),
+          eq(emailVerificationCodes.code, codeUpper),
+        ),
+      )
+      .limit(1);
+
+    if (!record) {
+      throw new AppError(ERROR_CODES.INVALID_CODE, 'Invalid or expired verification code', 400);
+    }
+
+    if (record.expiresAt < new Date()) {
+      await this.db
+        .delete(emailVerificationCodes)
+        .where(eq(emailVerificationCodes.id, record.id));
+      throw new AppError(ERROR_CODES.INVALID_CODE, 'Verification code expired', 400);
+    }
+
+    const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+
+    if (!user) {
+      throw notFound('User not found');
+    }
+
+    if (user.emailVerifiedAt) {
+      throw new AppError(ERROR_CODES.ALREADY_VERIFIED, 'Email already verified', 400);
+    }
+
+    await this.db
+      .update(users)
+      .set({ emailVerifiedAt: new Date(), updatedAt: new Date() })
+      .where(eq(users.id, userId));
+
+    await this.db
+      .delete(emailVerificationCodes)
+      .where(eq(emailVerificationCodes.userId, userId));
+  }
+
+  async forgotPassword(email: string): Promise<ForgotPasswordResult> {
+    const [user] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.email, email.toLowerCase().trim()))
+      .limit(1);
+
+    if (!user) {
+      return {
+        token: '',
+        expiresAt: new Date(Date.now() + RESET_TOKEN_TTL_MS),
+      };
+    }
+
+    const token = randomBytes(32).toString('hex');
+    const tokenHash = hashToken(token);
+    const expiresAt = new Date(Date.now() + RESET_TOKEN_TTL_MS);
+
+    await this.db.insert(passwordResetTokens).values({
+      userId: user.id,
+      tokenHash,
+      expiresAt,
+    });
+
+    return { token, expiresAt };
+  }
+
+  async resetPassword(token: string, newPassword: string): Promise<void> {
+    const tokenHash = hashToken(token);
+
+    const [record] = await this.db
+      .select()
+      .from(passwordResetTokens)
+      .where(eq(passwordResetTokens.tokenHash, tokenHash))
+      .limit(1);
+
+    if (!record) {
+      throw new AppError(ERROR_CODES.INVALID_RESET_TOKEN, 'Invalid or expired reset token', 400);
+    }
+
+    if (record.expiresAt < new Date()) {
+      await this.db
+        .delete(passwordResetTokens)
+        .where(eq(passwordResetTokens.id, record.id));
+      throw new AppError(ERROR_CODES.INVALID_RESET_TOKEN, 'Reset token expired', 400);
+    }
+
+    const passwordHash = await hashPassword(newPassword);
+
+    await this.db
+      .update(users)
+      .set({ passwordHash, updatedAt: new Date() })
+      .where(eq(users.id, record.userId));
+
+    await this.db
+      .delete(passwordResetTokens)
+      .where(eq(passwordResetTokens.id, record.id));
+  }
+}

src/services/llm/llm.service.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { env } from '../../config/env.js';
+import type { Stack, Level, QuestionType } from '../../db/schema/enums.js';
+
+export interface LlmConfig {
+  baseUrl: string;
+  model: string;
+  fallbackModel?: string;
+  apiKey?: string;
+  timeoutMs: number;
+  temperature: number;
+  maxTokens: number;
+  maxRetries: number;
+  retryDelayMs: number;
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface ChatCompletionResponse {
+  choices: Array<{
+    message?: { content: string };
+    text?: string;
+  }>;
+}
+
+const QUESTION_TYPES: QuestionType[] = ['single_choice', 'multiple_select', 'true_false', 'short_text'];
+
+const optionSchema = z.object({
+  key: z.string().min(1),
+  text: z.string().min(1),
+});
+
+const generatedQuestionSchema = z.object({
+  questionText: z.string().min(1),
+  type: z.enum(QUESTION_TYPES as [string, ...string[]]),
+  options: z.array(optionSchema).optional(),
+  correctAnswer: z.union([z.string(), z.array(z.string())]),
+  explanation: z.string().min(1),
+});
+
+const generateQuestionsResponseSchema = z.object({
+  questions: z.array(generatedQuestionSchema),
+});
+
+export type GeneratedQuestion = z.infer<typeof generatedQuestionSchema> & {
+  stack: Stack;
+  level: Level;
+};
+
+export interface GenerateQuestionsInput {
+  stack: Stack;
+  level: Level;
+  count: number;
+  types?: QuestionType[];
+}
+
+/** Metadata for persisting to question_cache_meta (used by QuestionService) */
+export interface LlmGenerationMeta {
+  llmModel: string;
+  promptHash: string;
+  generationTimeMs: number;
+  rawResponse: unknown;
+}
+
+export interface GenerateQuestionsResult {
+  questions: GeneratedQuestion[];
+  meta: LlmGenerationMeta;
+}
+
+export class LlmService {
+  private readonly config: LlmConfig;
+
+  constructor(config?: Partial<LlmConfig>) {
+    this.config = {
+      baseUrl: config?.baseUrl ?? env.LLM_BASE_URL,
+      model: config?.model ?? env.LLM_MODEL,
+      fallbackModel: config?.fallbackModel ?? env.LLM_FALLBACK_MODEL,
+      apiKey: config?.apiKey ?? env.LLM_API_KEY,
+      timeoutMs: config?.timeoutMs ?? env.LLM_TIMEOUT_MS,
+      temperature: config?.temperature ?? env.LLM_TEMPERATURE,
+      maxTokens: config?.maxTokens ?? env.LLM_MAX_TOKENS,
+      maxRetries: config?.maxRetries ?? env.LLM_MAX_RETRIES,
+      retryDelayMs: config?.retryDelayMs ?? env.LLM_RETRY_DELAY_MS,
+    };
+  }
+
+  async chat(messages: ChatMessage[]): Promise<string> {
+    const { content } = await this.chatWithMeta(messages);
+    return content;
+  }
+
+  /** Returns content and model used (for logging to question_cache_meta) */
+  async chatWithMeta(messages: ChatMessage[]): Promise<{ content: string; model: string }> {
+    let lastError: Error | null = null;
+
+    const modelsToTry = [this.config.model];
+    if (this.config.fallbackModel) {
+      modelsToTry.push(this.config.fallbackModel);
+    }
+
+    for (const model of modelsToTry) {
+      for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+        try {
+          const content = await this.executeChat(messages, model);
+          return { content, model };
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error('LLM request failed');
+          if (attempt < this.config.maxRetries) {
+            const delayMs = this.config.retryDelayMs * Math.pow(2, attempt);
+            await sleep(delayMs);
+          }
+        }
+      }
+    }
+
+    throw lastError ?? new Error('LLM request failed');
+  }
+
+  private async executeChat(messages: ChatMessage[], model: string): Promise<string> {
+    const url = `${this.config.baseUrl.replace(/\/$/, '')}/chat/completions`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.config.apiKey) {
+      headers['Authorization'] = `Bearer ${this.config.apiKey}`;
+    }
+
+    const body = {
+      model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      temperature: this.config.temperature,
+      max_tokens: this.config.maxTokens,
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`LLM request failed: ${res.status} ${res.statusText} - ${text}`);
+      }
+
+      const data = (await res.json()) as ChatCompletionResponse;
+
+      const choice = data.choices?.[0];
+      const content = choice?.message?.content ?? choice?.text ?? '';
+
+      return content.trim();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error) {
+        throw err;
+      }
+      throw new Error('LLM request failed');
+    }
+  }
+
+  async generateQuestions(input: GenerateQuestionsInput): Promise<GenerateQuestionsResult> {
+    const { stack, level, count, types = QUESTION_TYPES } = input;
+
+    const typeList = types.join(', ');
+    const systemPrompt = `You are a technical interview question generator. Generate exactly ${count} programming/tech questions.
+Return ONLY valid JSON in this exact format (no markdown, no code blocks):
+{"questions":[{"questionText":"...","type":"single_choice|multiple_select|true_false|short_text","options":[{"key":"a","text":"..."}],"correctAnswer":"a" or ["a","b"],"explanation":"..."}]}
+Rules: type must be one of: ${typeList}. For single_choice/multiple_select: options array required with key (a,b,c,d). For true_false: options [{"key":"true","text":"True"},{"key":"false","text":"False"}]. For short_text: options omitted, correctAnswer is string.`;
+
+    const userPrompt = `Generate ${count} questions for stack="${stack}", level="${level}". Use types: ${typeList}.`;
+
+    const promptForHash = systemPrompt + '\n---\n' + userPrompt;
+    const promptHash = createHash('sha256').update(promptForHash).digest('hex');
+
+    const start = Date.now();
+    const { content: raw, model } = await this.chatWithMeta([
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ]);
+    const generationTimeMs = Date.now() - start;
+
+    const jsonStr = extractJson(raw);
+    const parsed = JSON.parse(jsonStr) as unknown;
+
+    const result = generateQuestionsResponseSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new Error(`LLM response validation failed: ${result.error.message}`);
+    }
+
+    const questions: GeneratedQuestion[] = result.data.questions.map((q) => ({
+      ...q,
+      stack,
+      level,
+    }));
+
+    for (const q of questions) {
+      if ((q.type === 'single_choice' || q.type === 'multiple_select') && (!q.options || q.options.length === 0)) {
+        throw new Error(`Question validation failed: ${q.type} requires options`);
+      }
+      if (q.type === 'true_false' && (!q.options || q.options.length < 2)) {
+        throw new Error(`Question validation failed: true_false requires true/false options`);
+      }
+    }
+
+    return {
+      questions,
+      meta: {
+        llmModel: model,
+        promptHash,
+        generationTimeMs,
+        rawResponse: parsed,
+      },
+    };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function extractJson(text: string): string {
+  const trimmed = text.trim();
+  const match = trimmed.match(/\{[\s\S]*\}/);
+  return match ? match[0]! : trimmed;
+}

src/services/questions/question.service.ts

@@ -0,0 +1,197 @@
+import { eq, and, sql, asc, inArray } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import {
+  questionBank,
+  questionCacheMeta,
+  userQuestionLog,
+} from '../../db/schema/index.js';
+import { internalError, AppError, ERROR_CODES } from '../../utils/errors.js';
+import type { Stack, Level, QuestionType } from '../../db/schema/enums.js';
+import type {
+  GeneratedQuestion,
+  GenerateQuestionsResult,
+} from '../llm/llm.service.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type QuestionForTest = {
+  questionBankId: string;
+  type: QuestionType;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+};
+
+export interface LlmServiceInterface {
+  generateQuestions(input: {
+    stack: Stack;
+    level: Level;
+    count: number;
+    types?: QuestionType[];
+  }): Promise<GenerateQuestionsResult>;
+}
+
+function shuffle<T>(arr: T[]): T[] {
+  const result = [...arr];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j]!, result[i]!];
+  }
+  return result;
+}
+
+export class QuestionService {
+  constructor(
+    private readonly db: Db,
+    private readonly llmService: LlmServiceInterface
+  ) {}
+
+  /**
+   * Get questions for a test. Fetches approved questions from question_bank.
+   * If not enough, generates via LLM, persists to question_bank and question_cache_meta.
+   */
+  async getQuestionsForTest(
+    userId: string,
+    stack: Stack,
+    level: Level,
+    count: number
+  ): Promise<QuestionForTest[]> {
+    const approved = await this.db
+      .select({
+        id: questionBank.id,
+        type: questionBank.type,
+        questionText: questionBank.questionText,
+        options: questionBank.options,
+        correctAnswer: questionBank.correctAnswer,
+        explanation: questionBank.explanation,
+      })
+      .from(questionBank)
+      .where(
+        and(eq(questionBank.stack, stack), eq(questionBank.level, level), eq(questionBank.status, 'approved'))
+      )
+      .orderBy(asc(questionBank.usageCount));
+
+    const seenIds = await this.db
+      .select({ questionBankId: userQuestionLog.questionBankId })
+      .from(userQuestionLog)
+      .where(eq(userQuestionLog.userId, userId));
+
+    const seenSet = new Set(seenIds.map((r) => r.questionBankId));
+    const preferred = approved.filter((q) => !seenSet.has(q.id));
+    const pool = preferred.length >= count ? preferred : approved;
+    const shuffled = shuffle(pool);
+
+    const fromBank: QuestionForTest[] = shuffled.slice(0, count).map((q) => ({
+      questionBankId: q.id,
+      type: q.type,
+      questionText: q.questionText,
+      options: q.options,
+      correctAnswer: q.correctAnswer,
+      explanation: q.explanation,
+    }));
+
+    let result = fromBank;
+
+    if (result.length < count) {
+      const generated = await this.generateAndPersistQuestions(
+        stack,
+        level,
+        count - result.length
+      );
+      result = [...result, ...generated];
+    }
+
+    if (result.length < count) {
+      throw new AppError(
+        ERROR_CODES.QUESTIONS_UNAVAILABLE,
+        'Not enough questions available for this stack and level',
+        422
+      );
+    }
+
+    if (result.length > 0) {
+      await this.db.insert(userQuestionLog).values(
+        result.map((q) => ({
+          userId,
+          questionBankId: q.questionBankId,
+        }))
+      );
+
+      const ids = result.map((q) => q.questionBankId);
+      await this.db
+        .update(questionBank)
+        .set({
+          usageCount: sql`${questionBank.usageCount} + 1`,
+        })
+        .where(inArray(questionBank.id, ids));
+    }
+
+    return result;
+  }
+
+  private async generateAndPersistQuestions(
+    stack: Stack,
+    level: Level,
+    count: number
+  ): Promise<QuestionForTest[]> {
+    let generated: GeneratedQuestion[];
+    let meta: GenerateQuestionsResult['meta'];
+
+    try {
+      const result = await this.llmService.generateQuestions({
+        stack,
+        level,
+        count,
+      });
+      generated = result.questions;
+      meta = result.meta;
+    } catch (err) {
+      throw internalError(
+        'Failed to generate questions',
+        err instanceof Error ? err : undefined
+      );
+    }
+
+    const inserted: QuestionForTest[] = [];
+
+    for (const q of generated) {
+      const [row] = await this.db
+        .insert(questionBank)
+        .values({
+          stack,
+          level,
+          type: q.type as QuestionType,
+          questionText: q.questionText,
+          options: q.options ?? null,
+          correctAnswer: q.correctAnswer,
+          explanation: q.explanation,
+          status: 'approved',
+          source: 'llm_generated',
+        })
+        .returning();
+
+      if (row) {
+        await this.db.insert(questionCacheMeta).values({
+          questionBankId: row.id,
+          llmModel: meta.llmModel,
+          promptHash: meta.promptHash,
+          generationTimeMs: meta.generationTimeMs,
+          rawResponse: meta.rawResponse,
+        });
+
+        inserted.push({
+          questionBankId: row.id,
+          type: row.type,
+          questionText: row.questionText,
+          options: row.options,
+          correctAnswer: row.correctAnswer,
+          explanation: row.explanation,
+        });
+      }
+    }
+
+    return inserted;
+  }
+}

src/services/tests/tests.service.ts

@@ -0,0 +1,399 @@
+import { eq, and, desc } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { tests, testQuestions, userStats } from '../../db/schema/index.js';
+import { notFound, conflict, AppError, ERROR_CODES } from '../../utils/errors.js';
+import type { Stack, Level, TestMode } from '../../db/schema/enums.js';
+import type { QuestionService } from '../questions/question.service.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type CreateTestInput = {
+  stack: Stack;
+  level: Level;
+  questionCount: number;
+  mode?: TestMode;
+};
+
+export type TestSnapshot = {
+  id: string;
+  testId: string;
+  questionBankId: string | null;
+  orderNumber: number;
+  type: string;
+  questionText: string;
+  options: Array<{ key: string; text: string }> | null;
+  correctAnswer: string | string[];
+  explanation: string;
+  userAnswer?: string | string[] | null;
+  isCorrect?: boolean | null;
+  answeredAt?: string | null;
+};
+
+export type TestWithQuestions = {
+  id: string;
+  userId: string;
+  stack: string;
+  level: string;
+  questionCount: number;
+  mode: string;
+  status: string;
+  score: number | null;
+  startedAt: string;
+  finishedAt: string | null;
+  timeLimitSeconds: number | null;
+  questions: TestSnapshot[];
+};
+
+export class TestsService {
+  constructor(
+    private readonly db: Db,
+    private readonly questionService: QuestionService
+  ) {}
+
+  /**
+   * Create a new test: fetch questions, create test record, snapshot questions into test_questions.
+   */
+  async createTest(userId: string, input: CreateTestInput): Promise<TestWithQuestions> {
+    const { stack, level, questionCount, mode = 'fixed' } = input;
+
+    if (questionCount < 1 || questionCount > 50) {
+      throw new AppError(
+        ERROR_CODES.BAD_REQUEST,
+        'questionCount must be between 1 and 50',
+        400
+      );
+    }
+
+    const questions = await this.questionService.getQuestionsForTest(
+      userId,
+      stack,
+      level,
+      questionCount
+    );
+
+    const [test] = await this.db
+      .insert(tests)
+      .values({
+        userId,
+        stack,
+        level,
+        questionCount,
+        mode,
+        status: 'in_progress',
+      })
+      .returning();
+
+    if (!test) {
+      throw new AppError(
+        ERROR_CODES.INTERNAL_ERROR,
+        'Failed to create test',
+        500
+      );
+    }
+
+    const tqValues = questions.map((q, i) => ({
+      testId: test.id,
+      questionBankId: q.questionBankId,
+      orderNumber: i + 1,
+      type: q.type,
+      questionText: q.questionText,
+      options: q.options,
+      correctAnswer: q.correctAnswer,
+      explanation: q.explanation,
+    }));
+
+    await this.db.insert(testQuestions).values(tqValues);
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, test.id))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(test, questionsRows);
+  }
+
+  /**
+   * Submit an answer for a question in an in-progress test.
+   */
+  async answerQuestion(
+    userId: string,
+    testId: string,
+    testQuestionId: string,
+    userAnswer: string | string[]
+  ): Promise<TestSnapshot> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) {
+      throw notFound('Test not found');
+    }
+    if (test.status !== 'in_progress') {
+      throw conflict(ERROR_CODES.TEST_ALREADY_FINISHED, 'Test is already finished');
+    }
+
+    const [tq] = await this.db
+      .select()
+      .from(testQuestions)
+      .where(
+        and(
+          eq(testQuestions.id, testQuestionId),
+          eq(testQuestions.testId, testId)
+        )
+      )
+      .limit(1);
+
+    if (!tq) {
+      throw conflict(ERROR_CODES.WRONG_QUESTION, 'Question does not belong to this test');
+    }
+    if (tq.userAnswer !== null && tq.userAnswer !== undefined) {
+      throw conflict(ERROR_CODES.QUESTION_ALREADY_ANSWERED, 'Question already answered');
+    }
+
+    const isCorrect = this.checkAnswer(tq.correctAnswer, userAnswer);
+
+    const [updated] = await this.db
+      .update(testQuestions)
+      .set({
+        userAnswer,
+        isCorrect,
+        answeredAt: new Date(),
+      })
+      .where(eq(testQuestions.id, testQuestionId))
+      .returning();
+
+    if (!updated) {
+      throw notFound('Question not found');
+    }
+
+    return {
+      id: updated.id,
+      testId: updated.testId,
+      questionBankId: updated.questionBankId,
+      orderNumber: updated.orderNumber,
+      type: updated.type,
+      questionText: updated.questionText,
+      options: updated.options,
+      correctAnswer: updated.correctAnswer,
+      explanation: updated.explanation,
+      userAnswer: updated.userAnswer,
+      isCorrect: updated.isCorrect,
+      answeredAt: updated.answeredAt?.toISOString() ?? null,
+    };
+  }
+
+  private checkAnswer(
+    correct: string | string[],
+    user: string | string[]
+  ): boolean {
+    if (Array.isArray(correct) && Array.isArray(user)) {
+      if (correct.length !== user.length) return false;
+      const a = [...correct].sort();
+      const b = [...user].sort();
+      return a.every((v, i) => v === b[i]);
+    }
+    if (typeof correct === 'string' && typeof user === 'string') {
+      return correct.trim().toLowerCase() === user.trim().toLowerCase();
+    }
+    return false;
+  }
+
+  /**
+   * Finish a test: calculate score, update user_stats.
+   */
+  async finishTest(userId: string, testId: string): Promise<TestWithQuestions> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) {
+      throw notFound('Test not found');
+    }
+    if (test.status !== 'in_progress') {
+      throw conflict(ERROR_CODES.TEST_ALREADY_FINISHED, 'Test is already finished');
+    }
+
+    const questions = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId));
+
+    const unanswered = questions.filter(
+      (q) => q.userAnswer === null || q.userAnswer === undefined
+    );
+    if (unanswered.length > 0) {
+      throw new AppError(
+        ERROR_CODES.NO_ANSWERS,
+        `Cannot finish: ${unanswered.length} question(s) not answered`,
+        422
+      );
+    }
+
+    const correctCount = questions.filter((q) => q.isCorrect === true).length;
+    const score = Math.round((correctCount / questions.length) * 100);
+
+    const [updatedTest] = await this.db
+      .update(tests)
+      .set({
+        status: 'completed',
+        score,
+        finishedAt: new Date(),
+      })
+      .where(eq(tests.id, testId))
+      .returning();
+
+    if (!updatedTest) {
+      throw notFound('Test not found');
+    }
+
+    await this.upsertUserStats(userId, test.stack as Stack, test.level as Level, {
+      totalQuestions: questions.length,
+      correctAnswers: correctCount,
+      testsTaken: 1,
+    });
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(updatedTest, questionsRows);
+  }
+
+  private async upsertUserStats(
+    userId: string,
+    stack: Stack,
+    level: Level,
+    delta: { totalQuestions: number; correctAnswers: number; testsTaken: number }
+  ): Promise<void> {
+    const [existing] = await this.db
+      .select()
+      .from(userStats)
+      .where(
+        and(
+          eq(userStats.userId, userId),
+          eq(userStats.stack, stack),
+          eq(userStats.level, level)
+        )
+      )
+      .limit(1);
+
+    const now = new Date();
+
+    if (existing) {
+      await this.db
+        .update(userStats)
+        .set({
+          totalQuestions: existing.totalQuestions + delta.totalQuestions,
+          correctAnswers: existing.correctAnswers + delta.correctAnswers,
+          testsTaken: existing.testsTaken + delta.testsTaken,
+          lastTestAt: now,
+        })
+        .where(eq(userStats.id, existing.id));
+    } else {
+      await this.db.insert(userStats).values({
+        userId,
+        stack,
+        level,
+        totalQuestions: delta.totalQuestions,
+        correctAnswers: delta.correctAnswers,
+        testsTaken: delta.testsTaken,
+        lastTestAt: now,
+      });
+    }
+  }
+
+  /**
+   * Get a single test by ID (must belong to user).
+   */
+  async getById(userId: string, testId: string): Promise<TestWithQuestions | null> {
+    const [test] = await this.db
+      .select()
+      .from(tests)
+      .where(and(eq(tests.id, testId), eq(tests.userId, userId)))
+      .limit(1);
+
+    if (!test) return null;
+
+    const questionsRows = await this.db
+      .select()
+      .from(testQuestions)
+      .where(eq(testQuestions.testId, testId))
+      .orderBy(testQuestions.orderNumber);
+
+    return this.toTestWithQuestions(test, questionsRows);
+  }
+
+  /**
+   * Get test history for a user (most recent first).
+   */
+  async getHistory(
+    userId: string,
+    options?: { limit?: number; offset?: number }
+  ): Promise<{ tests: TestWithQuestions[]; total: number }> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const offset = options?.offset ?? 0;
+
+    const all = await this.db
+      .select()
+      .from(tests)
+      .where(eq(tests.userId, userId))
+      .orderBy(desc(tests.startedAt));
+
+    const total = all.length;
+    const page = all.slice(offset, offset + limit);
+
+    const result: TestWithQuestions[] = [];
+
+    for (const test of page) {
+      const questionsRows = await this.db
+        .select()
+        .from(testQuestions)
+        .where(eq(testQuestions.testId, test.id))
+        .orderBy(testQuestions.orderNumber);
+      result.push(this.toTestWithQuestions(test, questionsRows));
+    }
+
+    return { tests: result, total };
+  }
+
+  private toTestWithQuestions(
+    test: (typeof tests.$inferSelect),
+    questionsRows: (typeof testQuestions.$inferSelect)[]
+  ): TestWithQuestions {
+    return {
+      id: test.id,
+      userId: test.userId,
+      stack: test.stack,
+      level: test.level,
+      questionCount: test.questionCount,
+      mode: test.mode,
+      status: test.status,
+      score: test.score,
+      startedAt: test.startedAt.toISOString(),
+      finishedAt: test.finishedAt?.toISOString() ?? null,
+      timeLimitSeconds: test.timeLimitSeconds,
+      questions: questionsRows.map((q) => ({
+        id: q.id,
+        testId: q.testId,
+        questionBankId: q.questionBankId,
+        orderNumber: q.orderNumber,
+        type: q.type,
+        questionText: q.questionText,
+        options: q.options,
+        correctAnswer: q.correctAnswer,
+        explanation: q.explanation,
+        userAnswer: q.userAnswer,
+        isCorrect: q.isCorrect,
+        answeredAt: q.answeredAt?.toISOString() ?? null,
+      })),
+    };
+  }
+}

src/services/user/user.service.ts

@@ -0,0 +1,175 @@
+import { eq } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../db/schema/index.js';
+import { users, userStats } from '../../db/schema/index.js';
+import { notFound, conflict, ERROR_CODES } from '../../utils/errors.js';
+import type { User } from '../../db/schema/users.js';
+import type { SelfLevel } from '../../db/schema/index.js';
+
+type Db = NodePgDatabase<typeof schema>;
+
+export type UserStatItem = {
+  stack: string;
+  level: string;
+  totalQuestions: number;
+  correctAnswers: number;
+  testsTaken: number;
+  lastTestAt: string | null;
+};
+
+export type ProfileStats = {
+  byStack: UserStatItem[];
+  totalTestsTaken: number;
+  totalQuestions: number;
+  correctAnswers: number;
+  accuracy: number | null;
+};
+
+export type ProfileUpdateInput = {
+  nickname?: string;
+  avatarUrl?: string | null;
+  country?: string | null;
+  city?: string | null;
+  selfLevel?: SelfLevel | null;
+  isPublic?: boolean;
+};
+
+export type PublicProfile = {
+  id: string;
+  nickname: string;
+  avatarUrl: string | null;
+  country: string | null;
+  city: string | null;
+  selfLevel: string | null;
+  isPublic: boolean;
+  stats: ProfileStats;
+};
+
+export type PrivateProfile = PublicProfile & {
+  email: string;
+  emailVerifiedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+async function getStatsForUser(db: Db, userId: string): Promise<ProfileStats> {
+  const rows = await db
+    .select()
+    .from(userStats)
+    .where(eq(userStats.userId, userId));
+
+  const byStack: UserStatItem[] = rows.map((r) => ({
+    stack: r.stack,
+    level: r.level,
+    totalQuestions: r.totalQuestions,
+    correctAnswers: r.correctAnswers,
+    testsTaken: r.testsTaken,
+    lastTestAt: r.lastTestAt?.toISOString() ?? null,
+  }));
+
+  const totalTestsTaken = rows.reduce((sum, r) => sum + r.testsTaken, 0);
+  const totalQuestions = rows.reduce((sum, r) => sum + r.totalQuestions, 0);
+  const correctAnswers = rows.reduce((sum, r) => sum + r.correctAnswers, 0);
+  const accuracy = totalQuestions > 0 ? correctAnswers / totalQuestions : null;
+
+  return { byStack, totalTestsTaken, totalQuestions, correctAnswers, accuracy };
+}
+
+function toPublicProfile(user: User, stats: ProfileStats): PublicProfile {
+  return {
+    id: user.id,
+    nickname: user.nickname,
+    avatarUrl: user.avatarUrl,
+    country: user.country,
+    city: user.city,
+    selfLevel: user.selfLevel,
+    isPublic: user.isPublic,
+    stats,
+  };
+}
+
+function toPrivateProfile(user: User, stats: ProfileStats): PrivateProfile {
+  return {
+    ...toPublicProfile(user, stats),
+    email: user.email,
+    emailVerifiedAt: user.emailVerifiedAt?.toISOString() ?? null,
+    createdAt: user.createdAt.toISOString(),
+    updatedAt: user.updatedAt.toISOString(),
+  };
+}
+
+export class UserService {
+  constructor(private readonly db: Db) {}
+
+  async getById(userId: string): Promise<User | null> {
+    const [user] = await this.db.select().from(users).where(eq(users.id, userId)).limit(1);
+    return user ?? null;
+  }
+
+  async getByNickname(nickname: string): Promise<User | null> {
+    const [user] = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.nickname, nickname.trim()))
+      .limit(1);
+    return user ?? null;
+  }
+
+  async getPrivateProfile(userId: string): Promise<PrivateProfile> {
+    const [user, stats] = await Promise.all([this.getById(userId), getStatsForUser(this.db, userId)]);
+    if (!user) {
+      throw notFound('User not found');
+    }
+    return toPrivateProfile(user, stats);
+  }
+
+  async getPublicProfile(username: string): Promise<PublicProfile> {
+    const user = await this.getByNickname(username);
+    if (!user) {
+      throw notFound('User not found');
+    }
+    if (!user.isPublic) {
+      throw notFound('User not found');
+    }
+    const stats = await getStatsForUser(this.db, user.id);
+    return toPublicProfile(user, stats);
+  }
+
+  async updateProfile(userId: string, input: ProfileUpdateInput): Promise<PrivateProfile> {
+    const updateData: Partial<typeof users.$inferInsert> = {
+      updatedAt: new Date(),
+    };
+
+    if (input.nickname !== undefined) {
+      const trimmed = input.nickname.trim();
+      const [existing] = await this.db
+        .select({ id: users.id })
+        .from(users)
+        .where(eq(users.nickname, trimmed))
+        .limit(1);
+
+      if (existing && existing.id !== userId) {
+        throw conflict(ERROR_CODES.NICKNAME_TAKEN, 'Nickname already taken');
+      }
+      updateData.nickname = trimmed;
+    }
+    if (input.avatarUrl !== undefined) updateData.avatarUrl = input.avatarUrl;
+    if (input.country !== undefined) updateData.country = input.country;
+    if (input.city !== undefined) updateData.city = input.city;
+    if (input.selfLevel !== undefined) updateData.selfLevel = input.selfLevel;
+    if (input.isPublic !== undefined) updateData.isPublic = input.isPublic;
+
+    const [updated] = await this.db
+      .update(users)
+      .set(updateData)
+      .where(eq(users.id, userId))
+      .returning();
+
+    if (!updated) {
+      throw notFound('User not found');
+    }
+
+    const stats = await getStatsForUser(this.db, userId);
+    return toPrivateProfile(updated, stats);
+  }
+}

src/utils/errors.ts

@@ -0,0 +1,88 @@
+export const ERROR_CODES = {
+  BAD_REQUEST: 'BAD_REQUEST',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+  ACCOUNT_LOCKED: 'ACCOUNT_LOCKED',
+  EMAIL_TAKEN: 'EMAIL_TAKEN',
+  INVALID_REFRESH_TOKEN: 'INVALID_REFRESH_TOKEN',
+  TOKEN_REUSE_DETECTED: 'TOKEN_REUSE_DETECTED',
+  INVALID_CODE: 'INVALID_CODE',
+  ALREADY_VERIFIED: 'ALREADY_VERIFIED',
+  INVALID_RESET_TOKEN: 'INVALID_RESET_TOKEN',
+  NICKNAME_TAKEN: 'NICKNAME_TAKEN',
+  DAILY_LIMIT_REACHED: 'DAILY_LIMIT_REACHED',
+  EMAIL_NOT_VERIFIED: 'EMAIL_NOT_VERIFIED',
+  QUESTIONS_UNAVAILABLE: 'QUESTIONS_UNAVAILABLE',
+  QUESTION_ALREADY_ANSWERED: 'QUESTION_ALREADY_ANSWERED',
+  WRONG_QUESTION: 'WRONG_QUESTION',
+  TEST_ALREADY_FINISHED: 'TEST_ALREADY_FINISHED',
+  NO_ANSWERS: 'NO_ANSWERS',
+  TEST_NOT_FINISHED: 'TEST_NOT_FINISHED',
+  USER_NOT_FOUND: 'USER_NOT_FOUND',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+export class AppError extends Error {
+  constructor(
+    public readonly code: ErrorCode,
+    public readonly message: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Object.setPrototypeOf(this, AppError.prototype);
+  }
+
+  toJSON() {
+    const err: { code: string; message: string; details?: unknown } = {
+      code: this.code,
+      message: this.message,
+    };
+    if (this.details !== undefined) err.details = this.details;
+    return { error: err };
+  }
+}
+
+export function badRequest(message: string, details?: unknown): AppError {
+  return new AppError(ERROR_CODES.BAD_REQUEST, message, 400, details);
+}
+
+export function unauthorized(message: string): AppError {
+  return new AppError(ERROR_CODES.UNAUTHORIZED, message, 401);
+}
+
+export function forbidden(message: string): AppError {
+  return new AppError(ERROR_CODES.FORBIDDEN, message, 403);
+}
+
+export function notFound(message: string): AppError {
+  return new AppError(ERROR_CODES.NOT_FOUND, message, 404);
+}
+
+export function conflict(code: ErrorCode, message: string): AppError {
+  return new AppError(code, message, 409);
+}
+
+export function validationError(message: string, details?: unknown): AppError {
+  return new AppError(ERROR_CODES.VALIDATION_ERROR, message, 422, details);
+}
+
+export function rateLimitExceeded(message: string, retryAfter?: number): AppError {
+  const err = new AppError(ERROR_CODES.RATE_LIMIT_EXCEEDED, message, 429);
+  if (retryAfter !== undefined) {
+    (err as AppError & { retryAfter: number }).retryAfter = retryAfter;
+  }
+  return err;
+}
+
+export function internalError(message: string, cause?: unknown): AppError {
+  return new AppError(ERROR_CODES.INTERNAL_ERROR, message, 500, cause);
+}

src/utils/jwt.ts

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+import * as jose from 'jose';
+import { env } from '../config/env.js';
+
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+export interface AccessPayload {
+  sub: string;
+  email: string;
+  type: 'access';
+}
+
+export interface RefreshPayload {
+  sub: string;
+  sid: string;
+  type: 'refresh';
+}
+
+type JwtPayload = AccessPayload | RefreshPayload;
+
+const secret = new TextEncoder().encode(env.JWT_SECRET);
+
+export async function signAccessToken(payload: Omit<AccessPayload, 'type'>): Promise<string> {
+  return new jose.SignJWT({ ...payload, type: 'access' })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(env.JWT_ACCESS_TTL)
+    .sign(secret);
+}
+
+export async function signRefreshToken(payload: Omit<RefreshPayload, 'type'>): Promise<string> {
+  return new jose.SignJWT({ ...payload, type: 'refresh' })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(env.JWT_REFRESH_TTL)
+    .sign(secret);
+}
+
+export async function verifyToken(token: string): Promise<JwtPayload> {
+  const { payload } = await jose.jwtVerify(token, secret);
+  return payload as unknown as JwtPayload;
+}
+
+export function isAccessPayload(p: JwtPayload): p is AccessPayload {
+  return p.type === 'access';
+}
+
+export function isRefreshPayload(p: JwtPayload): p is RefreshPayload {
+  return p.type === 'refresh';
+}

src/utils/loginLockout.ts

@@ -0,0 +1,106 @@
+import type { Redis } from 'ioredis';
+
+const WINDOW_15M_SEC = 15 * 60;   // 900
+const WINDOW_1H_SEC = 60 * 60;   // 3600
+const WINDOW_24H_SEC = 24 * 60 * 60; // 86400
+
+const THRESHOLD_15M = 5;
+const THRESHOLD_1H = 10;
+const THRESHOLD_24H = 20;
+
+const BLOCK_15M_SEC = WINDOW_15M_SEC;
+const BLOCK_1H_SEC = WINDOW_1H_SEC;
+const BLOCK_24H_SEC = WINDOW_24H_SEC;
+
+const KEY_PREFIX = 'lockout';
+
+function key15m(ip: string): string {
+  return `${KEY_PREFIX}:15m:${ip}`;
+}
+function key1h(ip: string): string {
+  return `${KEY_PREFIX}:1h:${ip}`;
+}
+function key24h(ip: string): string {
+  return `${KEY_PREFIX}:24h:${ip}`;
+}
+function keyBlocked(ip: string): string {
+  return `${KEY_PREFIX}:blocked:${ip}`;
+}
+
+/**
+ * Check if the IP is currently blocked due to progressive login lockout.
+ * @returns { blocked: true, retryAfter } if blocked, { blocked: false } otherwise
+ */
+export async function checkBlocked(
+  redis: Redis,
+  ip: string
+): Promise<{ blocked: boolean; retryAfter?: number }> {
+  const blockedKey = keyBlocked(ip);
+  const ttl = await redis.ttl(blockedKey);
+  if (ttl > 0) {
+    return { blocked: true, retryAfter: ttl };
+  }
+  return { blocked: false };
+}
+
+const RECORD_SCRIPT = `
+  local c15 = redis.call('INCR', KEYS[1])
+  if redis.call('TTL', KEYS[1]) == -1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
+  local c1h = redis.call('INCR', KEYS[2])
+  if redis.call('TTL', KEYS[2]) == -1 then redis.call('EXPIRE', KEYS[2], ARGV[2]) end
+  local c24 = redis.call('INCR', KEYS[3])
+  if redis.call('TTL', KEYS[3]) == -1 then redis.call('EXPIRE', KEYS[3], ARGV[3]) end
+  return {c15, c1h, c24}
+`;
+
+/**
+ * Record a failed login attempt. Increments counters and sets blocked key when thresholds are reached.
+ * Thresholds: 5 in 15m -> 15m block; 10 in 1h -> 1h block; 20 in 24h -> 24h block.
+ */
+export async function recordFailedAttempt(redis: Redis, ip: string): Promise<void> {
+  const k15 = key15m(ip);
+  const k1h = key1h(ip);
+  const k24 = key24h(ip);
+  const kBlocked = keyBlocked(ip);
+
+  const counts = (await redis.eval(
+    RECORD_SCRIPT,
+    3,
+    k15,
+    k1h,
+    k24,
+    String(WINDOW_15M_SEC),
+    String(WINDOW_1H_SEC),
+    String(WINDOW_24H_SEC)
+  )) as number[];
+
+  const count15m = counts[0] ?? 0;
+  const count1h = counts[1] ?? 0;
+  const count24h = counts[2] ?? 0;
+
+  let blockTtl = 0;
+  if (count24h >= THRESHOLD_24H) {
+    blockTtl = BLOCK_24H_SEC;
+  } else if (count1h >= THRESHOLD_1H) {
+    blockTtl = BLOCK_1H_SEC;
+  } else if (count15m >= THRESHOLD_15M) {
+    blockTtl = BLOCK_15M_SEC;
+  }
+
+  if (blockTtl > 0) {
+    await redis.setex(kBlocked, blockTtl, '1');
+  }
+}
+
+/**
+ * Clear all lockout counters and blocked state on successful login.
+ */
+export async function clearOnSuccess(redis: Redis, ip: string): Promise<void> {
+  const keys = [
+    key15m(ip),
+    key1h(ip),
+    key24h(ip),
+    keyBlocked(ip),
+  ];
+  await redis.del(...keys);
+}

src/utils/password.ts

@@ -0,0 +1,15 @@
+import * as argon2 from 'argon2';
+
+const HASH_OPTIONS: argon2.Options = {
+  type: argon2.argon2id,
+  memoryCost: 19456,
+  timeCost: 2,
+};
+
+export async function hashPassword(plain: string): Promise<string> {
+  return argon2.hash(plain, HASH_OPTIONS);
+}
+
+export async function verifyPassword(hash: string, plain: string): Promise<boolean> {
+  return argon2.verify(hash, plain);
+}

src/utils/uuid.ts

@@ -0,0 +1,37 @@
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate UUID v7 (time-ordered, sortable).
+ * Simplified implementation: timestamp (48 bit) + random (74 bit).
+ */
+export function uuid7(): string {
+  const timestamp = Date.now();
+  const random = randomBytes(10);
+
+  const high = (timestamp / 0x100000000) >>> 0;
+  const low = timestamp >>> 0;
+
+  const b = new Uint8Array(16);
+  b[0] = (high >> 24) & 0xff;
+  b[1] = (high >> 16) & 0xff;
+  b[2] = (high >> 8) & 0xff;
+  b[3] = high & 0xff;
+  b[4] = (low >> 24) & 0xff;
+  b[5] = (low >> 16) & 0xff;
+  b[6] = ((low >> 8) & 0x3f) | 0x70;
+  b[7] = low & 0xff;
+  b[8] = 0x80 | (random[0] & 0x3f);
+  b[9] = random[1];
+  b[10] = random[2];
+  b[11] = random[3];
+  b[12] = random[4];
+  b[13] = random[5];
+  b[14] = random[6];
+  b[15] = random[7];
+
+  const hex = Array.from(b)
+    .map((x) => x.toString(16).padStart(2, '0'))
+    .join('');
+
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

tests/helpers/build-admin-test-app.ts

@@ -0,0 +1,51 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { AppError } from '../../src/utils/errors.js';
+import { adminQuestionsRoutes } from '../../src/routes/admin/questions.js';
+import type { MockDb } from '../test-utils.js';
+import { createMockDb } from '../test-utils.js';
+
+const mockAdminUser = { id: 'admin-1', email: 'admin@test.com' };
+
+/**
+ * Build a minimal Fastify app for admin route integration tests.
+ * Bypasses real auth - preHandlers set req.user to mock admin.
+ */
+export async function buildAdminTestApp(mockDb?: MockDb): Promise<FastifyInstance> {
+  const db = mockDb ?? createMockDb();
+
+  const app = Fastify({
+    logger: false,
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+  });
+
+  app.setErrorHandler((err: unknown, _request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    if (err instanceof AppError) {
+      return reply.status(err.statusCode).send(err.toJSON());
+    }
+    if (error.validation) {
+      return reply.status(422).send({
+        error: { code: 'VALIDATION_ERROR', message: 'Validation failed', details: error.validation },
+      });
+    }
+    return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: error.message } });
+  });
+
+  app.decorate('db', db);
+  app.decorate('rateLimitOptions', {
+    apiAuthed: { max: 100, timeWindow: '1 minute' },
+  });
+  app.decorateRequest('user', undefined);
+  app.decorate('authenticate', async (req: { user?: { id: string; email: string } }) => {
+    req.user = mockAdminUser;
+  });
+  app.decorate('authenticateAdmin', async (req: { user?: { id: string; email: string } }) => {
+    if (!req.user) req.user = mockAdminUser;
+    (req.user as { role?: string }).role = 'admin';
+  });
+
+  await app.register(adminQuestionsRoutes, { prefix: '/admin' });
+
+  return app;
+}

tests/helpers/build-test-app.ts

@@ -0,0 +1,46 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { AppError } from '../../src/utils/errors.js';
+import { authRoutes } from '../../src/routes/auth.js';
+import type { MockDb } from '../test-utils.js';
+import { createMockDb } from '../test-utils.js';
+
+/**
+ * Build a minimal Fastify app for auth route integration tests.
+ * Uses mock db and rate limit options (no actual rate limiting).
+ */
+export async function buildAuthTestApp(mockDb?: MockDb): Promise<FastifyInstance> {
+  const db = mockDb ?? createMockDb();
+
+  const app = Fastify({
+    logger: false,
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+  });
+
+  app.setErrorHandler((err: unknown, request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    if (err instanceof AppError) {
+      return reply.status(err.statusCode).send(err.toJSON());
+    }
+    if (error.validation) {
+      return reply.status(422).send({
+        error: { code: 'VALIDATION_ERROR', message: 'Validation failed', details: error.validation },
+      });
+    }
+    return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: error.message } });
+  });
+
+  app.decorate('db', db);
+  app.decorate('rateLimitOptions', {
+    login: { max: 100, timeWindow: '1 minute' },
+    register: { max: 100, timeWindow: '1 hour' },
+    forgotPassword: { max: 100, timeWindow: '1 hour' },
+    verifyEmail: { max: 100, timeWindow: '15 minutes' },
+    apiAuthed: { max: 100, timeWindow: '1 minute' },
+    apiGuest: { max: 100, timeWindow: '1 minute' },
+  });
+
+  await app.register(authRoutes, { prefix: '/auth' });
+
+  return app;
+}

tests/integration/admin.routes.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { buildAdminTestApp } from '../helpers/build-admin-test-app.js';
+import {
+  createMockDb,
+  selectChainOrderedLimitOffset,
+  selectChainWhere,
+  updateChainReturning,
+  insertChain,
+} from '../test-utils.js';
+
+describe('Admin routes integration', () => {
+  let app: Awaited<ReturnType<typeof buildAdminTestApp>>;
+  let mockDb: ReturnType<typeof createMockDb>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    app = await buildAdminTestApp(mockDb as never);
+  });
+
+  describe('GET /admin/questions/pending', () => {
+    it('returns pending questions list', async () => {
+      const pendingQuestions = [
+        {
+          id: 'q-1',
+          stack: 'js',
+          level: 'beginner',
+          type: 'single_choice',
+          questionText: 'Test question?',
+          options: [{ key: 'a', text: 'A' }],
+          correctAnswer: 'a',
+          explanation: 'Exp',
+          source: 'manual',
+          createdAt: new Date(),
+        },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrderedLimitOffset(pendingQuestions))
+        .mockReturnValueOnce(selectChainWhere([{ count: 1 }]));
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/admin/questions/pending',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.questions).toHaveLength(1);
+      expect(body.questions[0].questionText).toBe('Test question?');
+      expect(body.total).toBe(1);
+    });
+  });
+
+  describe('POST /admin/questions/:questionId/approve', () => {
+    it('returns 204 on success', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([{ id: 'q-1' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/approve',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(204);
+    });
+
+    it('returns 404 when question not found', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/approve',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+
+  describe('POST /admin/questions/:questionId/reject', () => {
+    it('returns 204 on success', async () => {
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([{ id: 'q-1' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111/reject',
+        headers: { authorization: 'Bearer any-token' },
+      });
+
+      expect(res.statusCode).toBe(204);
+    });
+  });
+
+  describe('PATCH /admin/questions/:questionId', () => {
+    it('returns updated question', async () => {
+      const updatedQuestion = {
+        id: 'q-1',
+        stack: 'js',
+        level: 'intermediate',
+        type: 'single_choice',
+        questionText: 'Updated?',
+        options: [{ key: 'a', text: 'A' }],
+        correctAnswer: 'a',
+        explanation: 'Updated exp',
+        source: 'manual',
+        createdAt: new Date(),
+      };
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([updatedQuestion])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'PATCH',
+        url: '/admin/questions/11111111-1111-1111-1111-111111111111',
+        headers: { authorization: 'Bearer any-token' },
+        payload: { questionText: 'Updated?', explanation: 'Updated exp' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.questionText).toBe('Updated?');
+    });
+  });
+});

tests/integration/auth.routes.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { buildAuthTestApp } from '../helpers/build-test-app.js';
+import {
+  createMockDb,
+  selectChain,
+  insertChain,
+  updateChain,
+  deleteChain,
+} from '../test-utils.js';
+
+vi.mock('../../src/utils/password.js', () => ({
+  hashPassword: vi.fn().mockResolvedValue('hashed-password'),
+  verifyPassword: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock('../../src/utils/jwt.js', () => ({
+  signAccessToken: vi.fn().mockResolvedValue('access-token'),
+  signRefreshToken: vi.fn().mockResolvedValue('refresh-token'),
+  verifyToken: vi.fn(),
+  isRefreshPayload: vi.fn(),
+  hashToken: vi.fn((t: string) => `hash-${t}`),
+}));
+
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn(() => ({ toString: () => 'abc123' })),
+  randomUUID: vi.fn(() => 'uuid-session-1'),
+}));
+
+import { isRefreshPayload, verifyToken } from '../../src/utils/jwt.js';
+
+describe('Auth routes integration', () => {
+  let app: Awaited<ReturnType<typeof buildAuthTestApp>>;
+  let mockDb: ReturnType<typeof createMockDb>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    app = await buildAuthTestApp(mockDb as never);
+  });
+
+  describe('POST /auth/register', () => {
+    it('returns 201 with userId and verificationCode when registration succeeds', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'user-123' }]))
+        .mockReturnValueOnce(insertChain([]));
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/register',
+        payload: {
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        },
+      });
+
+      expect(res.statusCode).toBe(201);
+      const body = JSON.parse(res.body);
+      expect(body.userId).toBe('user-123');
+      expect(body.message).toContain('verify your email');
+      expect(body.verificationCode).toBeDefined();
+    });
+
+    it('returns 409 when email is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'existing', email: 'test@example.com' }])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/register',
+        payload: {
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        },
+      });
+
+      expect(res.statusCode).toBe(409);
+      const body = JSON.parse(res.body);
+      expect(body.error?.code).toBe('EMAIL_TAKEN');
+    });
+
+    it('returns 422 when validation fails', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/register',
+        payload: {
+          email: 'short',
+          password: '123', // too short
+          nickname: 'x', // too short
+        },
+      });
+
+      expect([400, 422]).toContain(res.statusCode);
+      const body = JSON.parse(res.body);
+      expect(body.error?.code ?? body.error).toBeDefined();
+    });
+  });
+
+  describe('POST /auth/login', () => {
+    it('returns tokens when credentials are valid', async () => {
+      const mockUser = {
+        id: 'user-1',
+        email: 'test@example.com',
+        passwordHash: 'hashed',
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockUser])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/login',
+        payload: { email: 'test@example.com', password: 'password123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.accessToken).toBe('access-token');
+      expect(body.refreshToken).toBe('refresh-token');
+    });
+
+    it('returns 401 when credentials are invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/login',
+        payload: { email: 'unknown@example.com', password: 'wrong' },
+      });
+
+      expect(res.statusCode).toBe(401);
+    });
+  });
+
+  describe('POST /auth/logout', () => {
+    it('returns 204 on success', async () => {
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/logout',
+        payload: { refreshToken: 'some-token' },
+      });
+
+      expect(res.statusCode).toBe(204);
+    });
+  });
+
+  describe('POST /auth/refresh', () => {
+    it('returns new tokens when refresh token is valid', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([{ id: 'sess-1', userId: 'user-1' }]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', email: 'test@example.com' }]));
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/refresh',
+        payload: { refreshToken: 'valid-refresh-token' },
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.accessToken).toBe('access-token');
+      expect(body.refreshToken).toBe('refresh-token');
+    });
+  });
+
+  describe('POST /auth/verify-email', () => {
+    it('returns success when code is valid', async () => {
+      const mockCode = {
+        id: 'code-1',
+        userId: 'user-1',
+        code: 'ABC123',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockCode]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', emailVerifiedAt: null }]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/verify-email',
+        payload: { userId: 'user-1', code: 'ABC123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('POST /auth/forgot-password', () => {
+    it('returns 200 with generic message', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/forgot-password',
+        payload: { email: 'test@example.com' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+
+  describe('POST /auth/reset-password', () => {
+    it('returns 200 when token is valid', async () => {
+      const mockRecord = {
+        id: 'rec-1',
+        userId: 'user-1',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockRecord])
+      );
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/auth/reset-password',
+        payload: { token: 'valid-token', newPassword: 'newPassword123' },
+      });
+
+      expect(res.statusCode).toBe(200);
+    });
+  });
+});

tests/services/auth.service.test.ts

@@ -0,0 +1,304 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AuthService } from '../../src/services/auth/auth.service.js';
+import {
+  createMockDb,
+  selectChain,
+  insertChain,
+  updateChain,
+  deleteChain,
+} from '../test-utils.js';
+
+vi.mock('../../src/utils/password.js', () => ({
+  hashPassword: vi.fn().mockResolvedValue('hashed-password'),
+  verifyPassword: vi.fn().mockResolvedValue(true),
+}));
+
+vi.mock('../../src/utils/jwt.js', () => ({
+  signAccessToken: vi.fn().mockResolvedValue('access-token'),
+  signRefreshToken: vi.fn().mockResolvedValue('refresh-token'),
+  verifyToken: vi.fn(),
+  isRefreshPayload: vi.fn(),
+  hashToken: vi.fn((t: string) => `hash-${t}`),
+}));
+
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn(() => ({
+    toString: () => 'abc123',
+  })),
+  randomUUID: vi.fn(() => 'uuid-session-1'),
+}));
+
+import { hashPassword, verifyPassword } from '../../src/utils/password.js';
+import { signAccessToken, signRefreshToken, verifyToken, isRefreshPayload } from '../../src/utils/jwt.js';
+
+describe('AuthService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let authService: AuthService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    authService = new AuthService(mockDb as never);
+  });
+
+  describe('register', () => {
+    it('registers a new user when email and nickname are available', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'user-123' }]))
+        .mockReturnValueOnce(insertChain([]));
+
+      const result = await authService.register({
+        email: 'test@example.com',
+        password: 'password123',
+        nickname: 'tester',
+      });
+
+      expect(result.userId).toBe('user-123');
+      expect(result.verificationCode).toBeDefined();
+      expect(hashPassword).toHaveBeenCalledWith('password123');
+    });
+
+    it('throws when email is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'existing', email: 'test@example.com' }])
+      );
+
+      await expect(
+        authService.register({
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        })
+      ).rejects.toMatchObject({ code: 'EMAIL_TAKEN' });
+    });
+
+    it('throws when nickname is already taken', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([]))
+        .mockReturnValueOnce(selectChain([{ id: 'existing', nickname: 'tester' }]));
+
+      await expect(
+        authService.register({
+          email: 'test@example.com',
+          password: 'password123',
+          nickname: 'tester',
+        })
+      ).rejects.toMatchObject({ code: 'NICKNAME_TAKEN' });
+    });
+  });
+
+  describe('login', () => {
+    it('returns tokens when credentials are valid', async () => {
+      const mockUser = {
+        id: 'user-1',
+        email: 'test@example.com',
+        passwordHash: 'hashed',
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockUser])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.login({
+        email: 'test@example.com',
+        password: 'password123',
+      });
+
+      expect(result.accessToken).toBe('access-token');
+      expect(result.refreshToken).toBe('refresh-token');
+      expect(verifyPassword).toHaveBeenCalledWith('hashed', 'password123');
+      expect(signAccessToken).toHaveBeenCalled();
+      expect(signRefreshToken).toHaveBeenCalled();
+    });
+
+    it('throws when user not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.login({ email: 'nonexistent@example.com', password: 'x' })
+      ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+
+    it('throws when password is wrong', async () => {
+      vi.mocked(verifyPassword).mockResolvedValueOnce(false);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com', passwordHash: 'hashed' }])
+      );
+
+      await expect(
+        authService.login({ email: 'test@example.com', password: 'wrong' })
+      ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+  });
+
+  describe('logout', () => {
+    it('deletes session by refresh token hash', async () => {
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.logout('some-refresh-token');
+
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+
+  describe('refresh', () => {
+    it('returns new tokens when refresh token is valid', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'sess-1', userId: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.refresh({
+        refreshToken: 'valid-refresh-token',
+      });
+
+      expect(result.accessToken).toBe('access-token');
+      expect(result.refreshToken).toBe('refresh-token');
+    });
+
+    it('throws when token is not a refresh payload', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        type: 'access',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(false);
+
+      await expect(
+        authService.refresh({ refreshToken: 'access-token' })
+      ).rejects.toMatchObject({ message: expect.stringContaining('Invalid refresh token') });
+    });
+
+    it('throws when session not found', async () => {
+      vi.mocked(verifyToken).mockResolvedValueOnce({
+        sub: 'user-1',
+        sid: 'sid-1',
+        type: 'refresh',
+      } as never);
+      vi.mocked(isRefreshPayload).mockReturnValueOnce(true);
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.refresh({ refreshToken: 'invalid-or-expired' })
+      ).rejects.toMatchObject({ code: 'INVALID_REFRESH_TOKEN' });
+    });
+  });
+
+  describe('verifyEmail', () => {
+    it('throws when verification code is invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.verifyEmail('user-1', 'WRONG')
+      ).rejects.toMatchObject({ code: 'INVALID_CODE' });
+    });
+
+    it('updates user and deletes code when valid', async () => {
+      const mockCode = {
+        id: 'code-1',
+        userId: 'user-1',
+        code: 'ABC123',
+        expiresAt: new Date(Date.now() + 60000),
+      };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockCode]))
+        .mockReturnValueOnce(selectChain([{ id: 'user-1', emailVerifiedAt: null }]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.verifyEmail('user-1', 'ABC123');
+
+      expect(mockDb.update).toHaveBeenCalled();
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+
+  describe('forgotPassword', () => {
+    it('returns empty token when user not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      const result = await authService.forgotPassword('unknown@example.com');
+
+      expect(result.token).toBe('');
+      expect(result.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it('returns token when user exists', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 'user-1', email: 'test@example.com' }])
+      );
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        insertChain([])
+      );
+
+      const result = await authService.forgotPassword('test@example.com');
+
+      expect(result.token).toBeDefined();
+      expect(result.token).not.toBe('');
+      expect(result.expiresAt).toBeInstanceOf(Date);
+    });
+  });
+
+  describe('resetPassword', () => {
+    it('throws when token is invalid', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([])
+      );
+
+      await expect(
+        authService.resetPassword('invalid-token', 'newPassword123')
+      ).rejects.toMatchObject({ code: 'INVALID_RESET_TOKEN' });
+    });
+
+    it('updates password when token is valid', async () => {
+      const mockRecord = { id: 'rec-1', userId: 'user-1', expiresAt: new Date(Date.now() + 60000) };
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([mockRecord])
+      );
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChain([{ id: 'user-1' }])
+      );
+      (mockDb.delete as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        deleteChain()
+      );
+
+      await authService.resetPassword('valid-token', 'newPassword123');
+
+      expect(hashPassword).toHaveBeenCalledWith('newPassword123');
+      expect(mockDb.update).toHaveBeenCalled();
+      expect(mockDb.delete).toHaveBeenCalled();
+    });
+  });
+});

tests/services/llm.service.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../src/config/env.js', () => ({
+  env: {
+    LLM_BASE_URL: 'http://test',
+    LLM_MODEL: 'test-model',
+    LLM_FALLBACK_MODEL: 'fallback-model',
+    LLM_API_KEY: 'key',
+    LLM_TIMEOUT_MS: 5000,
+    LLM_TEMPERATURE: 0.7,
+    LLM_MAX_TOKENS: 2048,
+    LLM_MAX_RETRIES: 1,
+    LLM_RETRY_DELAY_MS: 10,
+  },
+}));
+
+import { LlmService } from '../../src/services/llm/llm.service.js';
+
+const mockConfig = {
+  baseUrl: 'http://llm.test/v1',
+  model: 'test-model',
+  fallbackModel: 'fallback-model',
+  apiKey: 'test-key',
+  timeoutMs: 5000,
+  temperature: 0.7,
+  maxTokens: 2048,
+  maxRetries: 1,
+  retryDelayMs: 10,
+};
+
+const validQuestionsJson = JSON.stringify({
+  questions: [
+    {
+      questionText: 'What is 2+2?',
+      type: 'single_choice',
+      options: [{ key: 'a', text: '4' }, { key: 'b', text: '3' }],
+      correctAnswer: 'a',
+      explanation: 'Basic math',
+    },
+  ],
+});
+
+describe('LlmService', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    vi.stubGlobal('fetch', mockFetch);
+  });
+
+  describe('chat', () => {
+    it('returns content from LLM response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: 'Hello!' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chat([
+        { role: 'user', content: 'Hi' },
+      ]);
+
+      expect(result).toBe('Hello!');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://llm.test/v1/chat/completions',
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+            'Authorization': 'Bearer test-key',
+          }),
+        })
+      );
+    });
+  });
+
+  describe('chatWithMeta', () => {
+    it('returns content and model name', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: 'Response' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Response');
+      expect(result.model).toBe('test-model');
+    });
+
+    it('retries on failure then succeeds', async () => {
+      mockFetch
+        .mockRejectedValueOnce(new Error('Network error'))
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({
+            choices: [{ message: { content: 'Retry OK' } }],
+          }),
+        });
+
+      const service = new LlmService({ ...mockConfig, maxRetries: 1 });
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Retry OK');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('falls back to fallbackModel when primary fails', async () => {
+      // Primary model: 2 attempts (initial + 1 retry), both fail
+      mockFetch
+        .mockResolvedValueOnce({ ok: false, status: 500, statusText: 'Error', text: () => Promise.resolve('') })
+        .mockResolvedValueOnce({ ok: false, status: 500, statusText: 'Error', text: () => Promise.resolve('') })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({
+            choices: [{ message: { content: 'Fallback OK' } }],
+          }),
+        });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.chatWithMeta([{ role: 'user', content: 'Q' }]);
+
+      expect(result.content).toBe('Fallback OK');
+      expect(result.model).toBe('fallback-model');
+    });
+
+    it('throws when all attempts fail', async () => {
+      mockFetch.mockRejectedValue(new Error('Network error'));
+
+      const service = new LlmService({ ...mockConfig, maxRetries: 0 });
+      await expect(
+        service.chatWithMeta([{ role: 'user', content: 'Q' }])
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('generateQuestions', () => {
+    it('returns validated questions with meta', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: validQuestionsJson } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.generateQuestions({
+        stack: 'js',
+        level: 'beginner',
+        count: 1,
+      });
+
+      expect(result.questions).toHaveLength(1);
+      expect(result.questions[0].questionText).toBe('What is 2+2?');
+      expect(result.questions[0].stack).toBe('js');
+      expect(result.questions[0].level).toBe('beginner');
+      expect(result.meta.llmModel).toBe('test-model');
+      expect(result.meta.promptHash).toBeDefined();
+      expect(result.meta.generationTimeMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('extracts JSON from markdown code block', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: '```json\n' + validQuestionsJson + '\n```' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      const result = await service.generateQuestions({
+        stack: 'ts',
+        level: 'intermediate',
+        count: 1,
+      });
+
+      expect(result.questions).toHaveLength(1);
+      expect(result.questions[0].type).toBe('single_choice');
+    });
+
+    it('throws when response validation fails', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: '{"invalid": "response"}' } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      await expect(
+        service.generateQuestions({ stack: 'js', level: 'beginner', count: 1 })
+      ).rejects.toThrow('LLM response validation failed');
+    });
+
+    it('throws when single_choice has no options', async () => {
+      const invalidJson = JSON.stringify({
+        questions: [
+          {
+            questionText: 'Q?',
+            type: 'single_choice',
+            options: [],
+            correctAnswer: 'a',
+            explanation: 'e',
+          },
+        ],
+      });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({
+          choices: [{ message: { content: invalidJson } }],
+        }),
+      });
+
+      const service = new LlmService(mockConfig);
+      await expect(
+        service.generateQuestions({ stack: 'js', level: 'beginner', count: 1 })
+      ).rejects.toThrow('Question validation failed');
+    });
+  });
+});

tests/services/question.service.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { QuestionService } from '../../src/services/questions/question.service.js';
+import {
+  createMockDb,
+  selectChainOrdered,
+  selectChainSimple,
+  insertChain,
+  updateChain,
+} from '../test-utils.js';
+
+const mockLlmQuestions = [
+  {
+    questionBankId: 'qb-new',
+    type: 'single_choice' as const,
+    questionText: 'New question?',
+    options: [{ key: 'a', text: 'A' }, { key: 'b', text: 'B' }],
+    correctAnswer: 'a',
+    explanation: 'Explanation',
+    stack: 'js' as const,
+    level: 'beginner' as const,
+  },
+];
+
+describe('QuestionService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let mockLlmService: { generateQuestions: ReturnType<typeof vi.fn> };
+  let questionService: QuestionService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    mockLlmService = {
+      generateQuestions: vi.fn().mockResolvedValue({
+        questions: mockLlmQuestions,
+        meta: {
+          llmModel: 'test-model',
+          promptHash: 'hash',
+          generationTimeMs: 100,
+          rawResponse: {},
+        },
+      }),
+    };
+    questionService = new QuestionService(mockDb as never, mockLlmService as never);
+  });
+
+  describe('getQuestionsForTest', () => {
+    it('returns questions from bank when enough approved exist', async () => {
+      const approvedRows = [
+        {
+          id: 'qb-1',
+          type: 'single_choice',
+          questionText: 'Q1?',
+          options: [{ key: 'a', text: 'A' }],
+          correctAnswer: 'a',
+          explanation: 'e',
+        },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(approvedRows))
+        .mockReturnValueOnce(selectChainSimple([]));
+      (mockDb.insert as ReturnType<typeof vi.fn>).mockReturnValueOnce(insertChain([]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(updateChain([]));
+
+      const result = await questionService.getQuestionsForTest(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+
+      expect(result).toHaveLength(1);
+      expect(result[0].questionBankId).toBe('qb-1');
+      expect(mockLlmService.generateQuestions).not.toHaveBeenCalled();
+    });
+
+    it('calls LLM when not enough questions in bank', async () => {
+      const approvedRows: unknown[] = [];
+      const seenIds: unknown[] = [];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(approvedRows))
+        .mockReturnValueOnce(selectChainSimple(seenIds));
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([{ id: 'qb-new', ...mockLlmQuestions[0] }]))
+        .mockReturnValueOnce(insertChain([]))
+        .mockReturnValueOnce(insertChain([]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(updateChain([]));
+
+      const result = await questionService.getQuestionsForTest(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+
+      expect(result).toHaveLength(1);
+      expect(mockLlmService.generateQuestions).toHaveBeenCalledWith({
+        stack: 'js',
+        level: 'beginner',
+        count: 1,
+      });
+    });
+
+    it('throws when not enough questions available', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered([]))
+        .mockReturnValueOnce(selectChainSimple([]));
+      mockLlmService.generateQuestions.mockResolvedValueOnce({
+        questions: [],
+        meta: { llmModel: 'x', promptHash: 'y', generationTimeMs: 0, rawResponse: {} },
+      });
+
+      await expect(
+        questionService.getQuestionsForTest('user-1', 'js', 'beginner', 5)
+      ).rejects.toMatchObject({ code: 'QUESTIONS_UNAVAILABLE' });
+    });
+  });
+});

tests/services/tests.service.test.ts

@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TestsService } from '../../src/services/tests/tests.service.js';
+import {
+  createMockDb,
+  selectChain,
+  selectChainOrdered,
+  selectChainWhere,
+  insertChain,
+  updateChain,
+  updateChainReturning,
+} from '../test-utils.js';
+
+const mockQuestions = [
+  {
+    questionBankId: 'qb-1',
+    type: 'single_choice' as const,
+    questionText: 'What is 2+2?',
+    options: [{ key: 'a', text: '4' }, { key: 'b', text: '3' }],
+    correctAnswer: 'a',
+    explanation: 'Basic math',
+  },
+];
+
+describe('TestsService', () => {
+  let mockDb: ReturnType<typeof createMockDb>;
+  let mockQuestionService: { getQuestionsForTest: ReturnType<typeof vi.fn> };
+  let testsService: TestsService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb = createMockDb();
+    mockQuestionService = {
+      getQuestionsForTest: vi.fn().mockResolvedValue(mockQuestions),
+    };
+    testsService = new TestsService(mockDb as never, mockQuestionService as never);
+  });
+
+  describe('createTest', () => {
+    it('creates a test with questions from QuestionService', async () => {
+      const mockTest = {
+        id: 'test-1',
+        userId: 'user-1',
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 1,
+        mode: 'fixed',
+        status: 'in_progress',
+        score: null,
+        startedAt: new Date(),
+        finishedAt: null,
+        timeLimitSeconds: null,
+      };
+      const mockTqRows = [
+        {
+          id: 'tq-1',
+          testId: 'test-1',
+          questionBankId: 'qb-1',
+          orderNumber: 1,
+          type: 'single_choice',
+          questionText: 'What is 2+2?',
+          options: [{ key: 'a', text: '4' }],
+          correctAnswer: 'a',
+          explanation: 'Basic math',
+          userAnswer: null,
+          isCorrect: null,
+          answeredAt: null,
+        },
+      ];
+      (mockDb.insert as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(insertChain([mockTest]))
+        .mockReturnValueOnce(insertChain([]));
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChainOrdered(mockTqRows)
+      );
+
+      const result = await testsService.createTest('user-1', {
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 1,
+      });
+
+      expect(result.id).toBe('test-1');
+      expect(result.questions).toHaveLength(1);
+      expect(mockQuestionService.getQuestionsForTest).toHaveBeenCalledWith(
+        'user-1',
+        'js',
+        'beginner',
+        1
+      );
+    });
+
+    it('throws when questionCount is out of range', async () => {
+      await expect(
+        testsService.createTest('user-1', {
+          stack: 'js',
+          level: 'beginner',
+          questionCount: 0,
+        })
+      ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+
+      await expect(
+        testsService.createTest('user-1', {
+          stack: 'js',
+          level: 'beginner',
+          questionCount: 51,
+        })
+      ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+  });
+
+  describe('answerQuestion', () => {
+    it('returns updated question snapshot when answer is correct', async () => {
+      const mockTest = { id: 't-1', userId: 'user-1', status: 'in_progress' };
+      const mockTq = {
+        id: 'tq-1',
+        testId: 't-1',
+        correctAnswer: 'a',
+        userAnswer: null,
+        questionBankId: 'qb-1',
+        orderNumber: 1,
+        type: 'single_choice',
+        questionText: 'Q?',
+        options: [{ key: 'a', text: 'A' }],
+        explanation: 'exp',
+      };
+      const updatedTq = { ...mockTq, userAnswer: 'a', isCorrect: true, answeredAt: new Date() };
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChain([mockTq]));
+      (mockDb.update as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        updateChainReturning([updatedTq])
+      );
+
+      const result = await testsService.answerQuestion('user-1', 't-1', 'tq-1', 'a');
+
+      expect(result.isCorrect).toBe(true);
+      expect(result.userAnswer).toBe('a');
+    });
+
+    it('throws when test not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(selectChain([]));
+
+      await expect(
+        testsService.answerQuestion('user-1', 'bad-id', 'tq-1', 'a')
+      ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+    });
+
+    it('throws when test is already finished', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(
+        selectChain([{ id: 't-1', userId: 'user-1', status: 'completed' }])
+      );
+
+      await expect(
+        testsService.answerQuestion('user-1', 't-1', 'tq-1', 'a')
+      ).rejects.toMatchObject({ code: 'TEST_ALREADY_FINISHED' });
+    });
+  });
+
+  describe('finishTest', () => {
+    it('throws when there are unanswered questions', async () => {
+      const mockTest = { id: 't-1', userId: 'user-1', status: 'in_progress', stack: 'js', level: 'beginner' };
+      const mockQuestionsWithUnanswered = [
+        { id: 'tq-1', testId: 't-1', userAnswer: 'a', isCorrect: true },
+        { id: 'tq-2', testId: 't-1', userAnswer: null, isCorrect: null },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChainWhere(mockQuestionsWithUnanswered));
+
+      await expect(
+        testsService.finishTest('user-1', 't-1')
+      ).rejects.toMatchObject({ code: 'NO_ANSWERS' });
+    });
+  });
+
+  describe('getById', () => {
+    it('returns null when test not found', async () => {
+      (mockDb.select as ReturnType<typeof vi.fn>).mockReturnValueOnce(selectChain([]));
+
+      const result = await testsService.getById('user-1', 'bad-id');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns test with questions when found', async () => {
+      const mockTest = {
+        id: 't-1',
+        userId: 'user-1',
+        stack: 'js',
+        level: 'beginner',
+        questionCount: 2,
+        mode: 'fixed',
+        status: 'in_progress',
+        score: null,
+        startedAt: new Date(),
+        finishedAt: null,
+        timeLimitSeconds: null,
+      };
+      const mockTqRows = [
+        { id: 'tq-1', testId: 't-1', orderNumber: 1, questionBankId: 'qb-1', type: 'single_choice', questionText: 'Q1', options: [], correctAnswer: 'a', explanation: 'e', userAnswer: null, isCorrect: null, answeredAt: null },
+      ];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChain([mockTest]))
+        .mockReturnValueOnce(selectChainOrdered(mockTqRows));
+
+      const result = await testsService.getById('user-1', 't-1');
+
+      expect(result).not.toBeNull();
+      expect(result!.id).toBe('t-1');
+      expect(result!.questions).toHaveLength(1);
+    });
+  });
+
+  describe('getHistory', () => {
+    it('returns paginated test history', async () => {
+      const mockTests = [
+        { id: 't-1', userId: 'user-1', stack: 'js', level: 'beginner', questionCount: 1, mode: 'fixed', status: 'completed', score: 100, startedAt: new Date(), finishedAt: new Date(), timeLimitSeconds: null },
+      ];
+      const mockTqRows = [];
+      (mockDb.select as ReturnType<typeof vi.fn>)
+        .mockReturnValueOnce(selectChainOrdered(mockTests))
+        .mockReturnValueOnce(selectChainOrdered(mockTqRows));
+
+      const result = await testsService.getHistory('user-1', { limit: 10, offset: 0 });
+
+      expect(result.tests).toHaveLength(1);
+      expect(result.total).toBe(1);
+    });
+  });
+});

tests/setup.ts

@@ -0,0 +1,11 @@
+import { beforeAll, vi } from 'vitest';
+
+beforeAll(() => {
+  vi.stubEnv('NODE_ENV', 'test');
+  if (!process.env.DATABASE_URL) {
+    process.env.DATABASE_URL = 'postgresql://test:test@localhost:5432/test';
+  }
+  if (!process.env.JWT_SECRET) {
+    process.env.JWT_SECRET = 'test-secret-min-32-chars-long-for-validation';
+  }
+});

tests/smoke.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest';
+import { createMockDb } from './test-utils.js';
+
+describe('test-utils', () => {
+  it('createMockDb returns mock with select, insert, update, delete', () => {
+    const db = createMockDb();
+    expect(db.select).toBeDefined();
+    expect(db.insert).toBeDefined();
+    expect(db.update).toBeDefined();
+    expect(db.delete).toBeDefined();
+  });
+});

tests/test-utils.ts

@@ -0,0 +1,165 @@
+import { vi } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../src/db/schema/index.js';
+
+export type MockDb = {
+  select: ReturnType<NodePgDatabase<typeof schema>['select']>;
+  insert: ReturnType<NodePgDatabase<typeof schema>['insert']>;
+  update: ReturnType<NodePgDatabase<typeof schema>['update']>;
+  delete: ReturnType<NodePgDatabase<typeof schema>['delete']>;
+};
+
+/** Build a select chain that resolves to the given rows at .limit(n) */
+export function selectChain(resolveAtLimit: unknown[] = []) {
+  const limitFn = vi.fn().mockResolvedValue(resolveAtLimit);
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        limit: limitFn,
+        orderBy: vi.fn().mockReturnValue({ limit: limitFn }),
+      }),
+      limit: limitFn,
+    }),
+  };
+}
+
+/** Build a select chain for .from().where().orderBy() - orderBy is terminal */
+export function selectChainOrdered(resolveAtOrderBy: unknown[] = []) {
+  const orderByThenable = {
+    then: (resolve: (v: unknown) => void) => resolve(resolveAtOrderBy),
+  };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        orderBy: vi.fn().mockReturnValue(orderByThenable),
+      }),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where() with no orderBy - used by select({...}).from() */
+export function selectChainSimple(resolveRows: unknown[] = []) {
+  const thenable = { then: (resolve: (v: unknown) => void) => resolve(resolveRows) };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue(thenable),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where() - where is terminal (no orderBy/limit) */
+export function selectChainWhere(resolveAtWhere: unknown[] = []) {
+  const thenable = { then: (resolve: (v: unknown) => void) => resolve(resolveAtWhere) };
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue(thenable),
+    }),
+  };
+}
+
+/** Build a select chain for .from().where().orderBy().limit().offset() */
+export function selectChainOrderedLimitOffset(resolveRows: unknown[] = []) {
+  const offsetFn = vi.fn().mockResolvedValue(resolveRows);
+  return {
+    from: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        orderBy: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue({
+            offset: offsetFn,
+          }),
+        }),
+      }),
+    }),
+  };
+}
+
+/** Build an insert chain that resolves at .returning() or .values() */
+export function insertChain(resolveAtReturning: unknown[] = []) {
+  const returningFn = vi.fn().mockResolvedValue(resolveAtReturning);
+  const chainFromValues = {
+    returning: returningFn,
+    then: (resolve: (v?: unknown) => void) => resolve(undefined),
+  };
+  return {
+    values: vi.fn().mockReturnValue(chainFromValues),
+    returning: returningFn,
+  };
+}
+
+/** Build an update chain that resolves at .where() */
+export function updateChain(resolveAtWhere: unknown[] = []) {
+  return {
+    set: vi.fn().mockReturnValue({
+      where: vi.fn().mockResolvedValue(resolveAtWhere),
+    }),
+  };
+}
+
+/** Build an update chain with .where().returning() */
+export function updateChainReturning(resolveAtReturning: unknown[] = []) {
+  const returningFn = vi.fn().mockResolvedValue(resolveAtReturning);
+  return {
+    set: vi.fn().mockReturnValue({
+      where: vi.fn().mockReturnValue({
+        returning: returningFn,
+      }),
+    }),
+  };
+}
+
+/** Build a delete chain that resolves at .where() */
+export function deleteChain() {
+  return {
+    where: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+/**
+ * Create a chainable mock for Drizzle DB operations.
+ * Use mockReturnValue with selectChain/insertChain/updateChain/deleteChain.
+ */
+export function createMockDb(): MockDb {
+  const chain = {
+    from: vi.fn().mockReturnThis(),
+    where: vi.fn().mockReturnThis(),
+    values: vi.fn().mockReturnThis(),
+    set: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    returning: vi.fn().mockReturnThis(),
+  };
+
+  return {
+    select: vi.fn().mockReturnValue(chain),
+    insert: vi.fn().mockReturnValue(chain),
+    update: vi.fn().mockReturnValue(chain),
+    delete: vi.fn().mockReturnValue(chain),
+  } as unknown as MockDb;
+}
+
+/**
+ * Create a minimal mock Fastify app with db for route/integration tests.
+ * Use buildApp() from app.ts for full integration tests.
+ */
+export function createMockApp(): FastifyInstance & { db: MockDb } {
+  return {
+    db: createMockDb(),
+    log: {
+      child: () => ({
+        debug: () => {},
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        trace: () => {},
+        fatal: () => {},
+      }),
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      trace: () => {},
+      fatal: () => {},
+    },
+  } as FastifyInstance & { db: MockDb };
+}

vitest.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts', 'tests/**/*.spec.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'lcov'],
+      include: [
+        'src/services/auth/**/*.ts',
+        'src/services/llm/**/*.ts',
+        'src/services/questions/**/*.ts',
+        'src/services/tests/**/*.ts',
+        'src/services/admin/**/*.ts',
+      ],
+      exclude: [
+        'src/services/**/*.d.ts',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/index.ts',
+      ],
+      thresholds: {
+        lines: 70,
+        functions: 70,
+        branches: 68,
+        statements: 70,
+      },
+    },
+    setupFiles: ['tests/setup.ts'],
+    testTimeout: 10000,
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+});