DEBUG · Студенттер
Online coding contest for students: three timed rounds — Trace (read code), Debug (fix one line),
Build (write a function). Python runs in the browser (Pyodide), hidden tests are checked on the server,
live leaderboard, operator/admin panel, AI/copy analysis (never a verdict). UI in Kazakh.
Stack: Next.js 15 (App Router, React 19, TypeScript) · Prisma ORM + PostgreSQL · openapi.yml contract ·
one Docker image (static frontend + API) · Docker Compose · Playwright · GitHub Actions · AWS CloudFormation.
Live:
- https://debug-students.vercel.app — Vercel + Neon Postgres (deploys every push to
main through the Vercel GitHub integration).
- AWS — EC2 free tier, the same Docker image + Postgres + Caddy HTTPS, deployed by CI on every push to
main
(address: repository variable SITE_URL, see infra/aws/README.md).
Run with Docker (everything in containers)
cp .env.example .env # first time only: set SESSION_SECRET (≥ 32 chars), ADMIN_EMAIL, ADMIN_PASSWORD
docker compose up --build # app + PostgreSQL → http://localhost:3000 (admin: /admin)
docker compose down # stop, data stays in the pgdata volume · docker compose down -v — delete the data
The app container applies migrations on start and, with SEED_ON_START=1 (default in .env.example), creates the
admin and the first contest. GET /api/health → {"ok":true,"db":"up","version":"…"}.
Run for development (hot reload)
Node 22.9+, Docker for the database (or any PostgreSQL 15+).
npm install
cp .env.example .env # first time only (do not overwrite an existing .env)
npm run db:up # PostgreSQL from compose.yml on 127.0.0.1:${DB_PORT:-5432} (port busy? DB_PORT=5433 in .env)
npm run db:seed # admin + «DEBUG · Студенттер» contest with 16 tasks
npm run dev # applies migrations, http://localhost:3000
UI only, no backend: npm run dev:mock (MOCK badge; demo accounts [email protected] / demo-pass-1,
admin [email protected] / admin-pass-1, stored only in the browser).
Test
npm test # unit + frontend mock client + openapi contract + store contract (Memory, Postgres) + data import
npm run test:e2e # API e2e (contest, auth, admin) on the real server: memory and postgres
npm run test:pw:compose # Playwright: builds the image, starts app + Postgres, 15 feature specs + integration, desktop + 375 px
npm run build # type check + production build
Tests that need Postgres use TEST_DATABASE_URL (default postgresql://debug:debug@localhost:5432/debug); every run
creates its own schema and drops it afterwards.
CI/CD
.github/workflows/ci.yml on every push and pull request: unit (with a Postgres service) · api-e2e ·
build · docker-e2e (image + Compose + Playwright, report uploaded on failure) · infra-lint (cfn-lint).
On a push to main that passes everything, deploy assumes an AWS role through GitHub OIDC (no stored keys), pushes
the linux/amd64 image to ECR, rolls it out over SSM and waits until /api/health reports the commit SHA. Until the
repository variables from infra/aws/README.md exist, the deploy job is skipped with a notice.
Deploy
- Vercel + Neon: Vercel → project → Storage → Create Database → Neon → Connect (adds
DATABASE_URL,
DATABASE_URL_UNPOOLED, POSTGRES_PRISMA_URL). Project env: SESSION_SECRET, ADMIN_EMAIL, ADMIN_PASSWORD,
CRON_SECRET, NEXT_PUBLIC_SITE_URL. The build (scripts/vercel-build.sh) migrates through the unpooled URL, seeds
and builds; without a database URL it stops with a clear error.
- AWS (CloudFormation):
infra/aws/README.md — create/delete the stack, CI variables,
cost guardrails.
- Existing data → Postgres:
npm run db:import -- --from <libsql://… | postgresql://… | file:….db | export.json> (empty target,
one transaction, row counts compared); --export file.json to carry it to AWS.
Architecture
browser ── pages (app/) → lib/client api ─┬─ http.ts → /api/* route handlers → lib/server services → Store
└─ mock/ (mockService) ├─ MemoryStore
└─ PrismaStore → PostgreSQL
Docker image (Dockerfile): Next.js standalone server = public/ + .next/static + API, migrations on start
compose.yml: app + postgres:17 (volume) · compose.e2e.yml: test hooks for Playwright/CI
AWS (infra/aws): EC2 t3.micro → Caddy (HTTPS) → app (ECR) → Postgres (EBS) · GitHub OIDC + SSM deploys
AI-native workflow
chat-brainstorm.md — the brainstorm chat before building._docs/plan.md (spec), _docs/decisions.md (stack + architecture), _docs/design.md (design references)._docs/tasks.md → GitHub issues: mvp, post-mvp, user-test-bug, e2e-test, iteration labels iter-0 … iter-6.- Roles:
_docs/team/pm.md (grooming), qa.md (test cases), software-engineer.md, qa-engineer.md (verifies, closes).
- Iterations: frontend + mockService →
openapi.yml → in-memory backend → SQLite (Prisma) → connect →
test, containerise and deploy (PostgreSQL, Docker, Compose, Playwright per feature, CI/CD, AWS).
- Bugs found by running the app are
user-test-bug issues (Goal + Description → PM → QA test cases → fix → QA closes).
