dim

Dayaq — first DİM preparation demo

Azerbaijani exam-preparation application built with Next.js 16.3, React, strict TypeScript, Tailwind, Drizzle/PostgreSQL and Supabase Auth. Original content, deterministic grading, versioned attempts, and server authorization.

This is a working first demo, not a launch-ready education business. All seed content and mock scoring are explicitly demonstrations, not official DİM questions or predicted DİM scores. No default passwords or fabricated student activity are included.

Run locally (no external accounts required)

Install Node.js 24 LTS, version 24.15 or newer, and Git. Node 22.22.2+ is also supported by the dependencies. Use the committed lockfile.

git clone git@github.com:yusifm9/dim.git
cd dim
npm install

Copy the example environment file:

# Windows PowerShell
Copy-Item .env.example .env.local

# macOS / Linux
cp .env.example .env.local

Then run:

npm run db:migrate
npm run db:seed
npm run dev

Open http://localhost:3000 (the example environment and dev server use this host). Register your own account, choose I qrup Rİ / 2026 / Azərbaycan dili, then open Riyaziyyat. The initial dashboard is intentionally empty until you complete activities.

• After the first setup, launch with just npm run dev. Local mode needs no external service, credentials or internet connection once dependencies are installed.
• Local mode persists accounts, answers and content edits in .local/, excluded from Git.
• Local db:migrate executes the actual PostgreSQL migration and policies in an embedded PostgreSQL instance to validate them. The demo itself uses the atomic file adapter; it does not need a database server.
• db:seed is safe to repeat and does not erase existing accounts or progress. On an existing local store it inserts only demonstration content that store has never held, matched by identifier, so pulling new seed content (flashcards, key-concept sheets, papers) needs no reset and an edited or archived item is never overwritten.
• There are 24 original questions, seven question types, three complete topics (quadratic functions, Azerbaijani morphology, physics motion), one premium lesson example, eight exam tracks, and one 12-minute I qrup Rİ mock.
• Study tools on top of that bank: a difficulty-ordered question bank, a revision ladder per topic, 12 original flashcards with a Leitner scheduler, three key-concept sheets, a learner-built saved exam, and a paper archive holding three topic quizzes, one past-paper-style variant and one cohort variant. Every paper is original demonstration content.
• Verification and password-reset messages are written to .local/mail-outbox.ndjson. Open the latest matching URL in your browser. They are never returned by the public API. Local registration can be used before email confirmation; hosted Supabase can require confirmation.

Try the content/admin demo

Register a separate account normally, then grant its role from your terminal:

npm run db:set-role -- your-admin@example.com ADMIN
# Optional separate editor:
npm run db:set-role -- your-editor@example.com CONTENT_EDITOR

Open /admin. An editor can create a question, preview it, save a draft and submit it for review. An administrator can publish it. Existing attempts retain their original question snapshot. Administrator pages also manage curriculum, new exam tracks, per-subject question-type allocations, topics, lessons, mocks, roles, prices, manual entitlements and audit records. Question and lesson editors share safe rich-block controls; both support subtopic assignment.

For import, export an existing original question to see the schema. JSON accepts an array or { "questions": [...] }; CSV encodes nested arrays/answer keys as JSON cells. Imported rows must be drafts. Preview validation must pass before transactional commit.

Verify the build

npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e

Browser tests use installed Microsoft Edge on Windows. On other systems install Chromium once with npx playwright install chromium. Browser tests launch their own server on port 3100 and use isolated .local-e2e/ data. Stop a manually started dev server before testing/building to avoid competing Next.js output writes.

To preview the compiled build locally (terminal only; never configure this on Vercel):

$env:ALLOW_LOCAL_PRODUCTION='true'
npm start

ALLOW_LOCAL_PRODUCTION=true npm start

Deploy to Vercel with Supabase

The repository includes vercel.json; select the Next.js framework and Node.js 24.x. Build command is npm run build, install command is npm ci. No migration or destructive seed runs automatically during deployment.

1. Create a Supabase project. Enable email/password authentication.
2. Obtain its PostgreSQL connection string (server-side owner connection; Supabase pooler is supported with prepared statements disabled), project URL, and anon/publishable legacy API key.
3. Set .env.local temporarily to the hosted configuration below and run npm run db:migrate, then npm run db:seed. The scripts use a migration checksum ledger and normalized seed data. Keep real credentials out of Git.
4. Configure the same hosted variables in Vercel; deploy the main branch.
5. In Supabase Auth URL Configuration, set Site URL to the exact production HTTPS origin, and allow https://YOUR-DOMAIN/auth/callback. Set the email confirmation/recovery templates and email delivery settings for your project. Verify registration, verification and password reset with a real mailbox before public use.
6. Register the operator account and assign ADMIN using npm run db:set-role -- EMAIL ADMIN from a trusted terminal configured for the hosted database.
7. Smoke-test a full student journey and admin publication on the deployment. Local browser tests do not prove live Supabase delivery or hosting configuration.

Required Vercel variables:

Variable	Value
APP_MODE	supabase
DATABASE_URL	Supabase PostgreSQL URI; server secret, SSL required for remote database
NEXT_PUBLIC_SUPABASE_URL	https://PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon/public key; access still enforced by server and RLS
APP_URL	Exact production origin, e.g. https://example.vercel.app
NEXT_PUBLIC_APP_URL	Same exact production origin, without trailing slash
EPOINT_ENABLED	false for this demo

Leave ALLOW_LOCAL_PRODUCTION false/unset and do not deploy local mode. Hosted storage fails closed if credentials are missing; local filesystem data is never a production fallback. .env* and local stores are excluded from Git and server output tracing. Editor media uploads require server-only SUPABASE_SERVICE_ROLE_KEY and SUPABASE_MEDIA_BUCKET; follow private media setup and verify bucket policies before deployment.

The GitHub Actions workflow runs migrations/RLS, isolated seed, lint, route type generation, typecheck, tests, production build and the browser journeys on pushes to yusif-dev/main and pull requests. It uses Node 24, pinned action commits, read-only repository permissions and no production credentials. Browser failure diagnostics are retained for seven days; local stores and environment files are never uploaded.

The PostgreSQL role used by the server can read private answer keys and auth state; never expose DATABASE_URL to clients. Student-facing tables use explicit RLS; answer keys, raw snapshots, credentials and operational state live in a private schema. No dashboard/admin route is publicly indexed.

Current scope and limitations

Working locally: homepage/catalogue, register/login/logout, local verification/reset flow, onboarding, truthful dashboard, subject/topic lessons, completion/bookmarks, all seven answer controls, server grading/solutions, custom sample practice, mistakes, mastery/recommendations, timed mocks with autosave/refresh recovery, result breakdowns, and editorial draft/review/publish/import/export.

The study tools added on top of that core. Navigation is subject-first: a subject owns its own tools at /dashboard/subjects/<subject>/<tool>, so no surface mixes subjects together. Opening a tool from the sidebar without a subject shows a subject picker with per-subject counts rather than a combined list. Mistakes stay deliberately cross-subject, since that list is about your own wrong answers rather than one syllabus.

• Question bank ordering. The bank sorts easiest to hardest, with the direction under the learner’s control alongside the existing subject, topic, subtopic, difficulty and activity filters.
• Revision ladder. One climb per topic with a rung per difficulty. A rung is cleared on at least three distinct questions at 70% accuracy, and the next rung opens only then; an empty rung is transparent rather than a dead end. Derived from graded answers, so it needs no new stored state.
• Build my Exam. The learner picks scope and length; the server resolves the questions, owns the timing and saves the paper. Saved papers are re-sittable and each sitting is a fresh immutable attempt. Papers longer than five questions require CUSTOM_TESTS.
• Paper archive. Topic quizzes, a past-paper-style variant and a cohort variant are the same entity as a mock exam with a category, so they reuse timing, autosave, grading and result breakdowns. Worked solutions open only after submission, exactly as for mocks.
• Key concepts. Condensed single-screen sheets that reuse the lesson reader, its completion state and its bookmarks.
• Flashcards. A five-box Leitner scheduler (0/1/3/7/21 days). The server decides what is due and stores every review; the browser only walks the current sitting.

The question bank now applies answered, unanswered, incorrect and bookmarked filters to both the displayed list/count and generated sessions. An unsubmitted draft or blank response remains unanswered; a submitted written response awaiting review counts as answered.

Boundaries of this demo:

• Hosted Supabase Auth/email delivery and Vercel deployment need your credentials and an external smoke test. Supabase Storage uploads are not implemented; lesson assets are URL references.
• The question bank supports subtopic and activity filters; custom practice supports multiple topics. The chosen exam/year comes from the account target, with subjects driven by active versions.
• Past papers are not real DİM papers. The archive ships an original variant written to resemble the structure of earlier years, and the cohort variant is labelled a practice variant, never a prediction of DİM questions or of a DİM score. Republishing genuine DİM papers with worked solutions needs a licensing answer first; nothing in the code assumes one.
• Flashcard scheduling is per learner and deterministic, but there is no deck authoring in the admin workspace yet; cards ship from the seed.
• Only the seeded topics are covered. Other subject pages honestly indicate that content is being prepared. Official exam configurations and full scoring/rubrics are not published; all seed versions are marked official: false.
• Open responses save correctly and show rubrics/model answers, but require review; there is no AI grader or completed human grading queue.
• Mastery requires sufficient unique evidence. The tiny seed set cannot produce every highest mastery state.
• Premium is enforced server-side. Prices remain unconfigured. Epoint has a documented, unit-tested adapter, but live payments, renewals and merchant certification are not enabled or launch-validated. Do not enable billing for this demo.
• Analytics and monitoring are interfaces with inert defaults, not connected services.
• The repository adapter hydrates collections and serializes writes. This is acceptable for the first demo; query-specific repositories and load testing are needed before significant concurrent traffic.
• Legal pages are explicitly draft product policies and lack final operator/support details. They require review before public launch.

See docs/implementation-plan.md, docs/progress.md, docs/security.md, docs/database.md and docs/production-checklist.md for the implementation details and operational limits.

Troubleshooting

• Origin error: keep APP_URL and NEXT_PUBLIC_APP_URL identical to the browser origin (http://localhost:3000 by default). If upgrading from the first demo, change both old 127.0.0.1 values to localhost. Restart after changing env values. Production still requires an exact configured HTTPS origin.
• No mock available: the seed mock is for I qrup Rİ, 2026. Change the target in /dashboard/account.
• Cannot enter admin: assign the role to a registered account with the operator command above.
• Storage lock after a crash: stop all local app/test processes, verify the PID in .local/*.lock is no longer running, then remove only the stale lock. Never remove a live writer’s lock.
• PowerShell script policy: use npm.cmd in place of npm if the shell refuses npm.ps1.
• SSH push denied: install/authorize your GitHub SSH key, then run git push -u origin yusif-dev. No force push is needed.