hecz / study

An offline-first study-lab starter that turns your own notes and allowed resources into a personal loop: practice, review, compete, sync, repeat.

Live app · Build your bank · Class lab · Import format · Class pack

Built with Next.js, React, TypeScript, IndexedDB, Supabase, FSRS, Vitest, and Playwright.

Why This Exists

Most cert study tools feel like static question banks. hecz / study is built around momentum: answer a few questions, learn what changed, recover weak spots, and get the next useful action without turning study into a spreadsheet.

The public version is intentionally a starter kit. It ships the study engine, a tiny original demo bank, and docs for creating your own question bank from class notes, labs, official objectives, and resources you are allowed to use.

Your real learning bank should be yours.

What It Does

• Personal dashboard with predicted score, streaks, exam date pressure, weak areas, and a "Study this next" recommendation.
• Adaptive practice weighted toward weak domains, recent misses, and scheduled review.
• FSRS flashcards, MCQ review queues, wrong-answer recovery, bookmarks, PBQ drills, and acronym trainers.
• Multi-cert coverage for Security+ SY0-701, Network+ N10-009, A+ 220-1101, and A+ 220-1102.
• Local-first IndexedDB progress with optional Supabase auth and cloud sync.
• 1v1 duels with agreed question count, timer settings, rules preview, and server-authoritative scoring.
• HTTP study-agent surface for tools such as Cursor, OpenClaw, or personal scripts.

Bring Your Own Bank

The open-source repo does not include a full private or personal question bank. That is deliberate.

Use it as a lab:

• Clone the app.
• Import JSON/CSV from /import, or edit content/local-bank.ts if you prefer code.
• Add original questions, flashcards, PBQ-style drills, and acronyms.
• Track sources and licenses.
• Run short sessions and improve weak explanations after misses.

Start here:

• Build your own question bank
• Question bank format
• Class study lab
• Downloadable class pack

Do not add exam dumps, leaked questions, copied paid-course banks, or private material you do not have permission to reuse.

Technical Highlights

• Local-first product architecture keeps the core study loop fast and available without sign-in.
• Adaptive learning combines practice history, FSRS review, wrong-answer recovery, and weak-objective recommendations.
• Server-authoritative competition keeps duel timing, scoring, XP, and round advancement fair.
• Supabase migrations, RLS-backed tables, and server-only service-role paths keep privileged data access scoped.
• CI covers linting, unit tests, browser smoke tests, and production builds.

What I Learned

This project is practice in building product loops, not just screens. The hard parts have been deciding what the learner should do next, making offline progress feel trustworthy, keeping competition clear, and separating the reusable engine from private learning content.

Personal notes to fill in later:

• Why I built it: TODO
• Hardest tradeoff: TODO
• Favorite implementation detail: TODO
• What I would improve next: TODO

Run locally

Prerequisite: Node.js 22+.

npm install
npm run dev

Open the local URL printed by Next.js, usually http://localhost:3000.

Useful scripts:

npm run lint
npm test
npm run e2e
npm run build

Environment variables

The app runs locally without cloud sync. Optional server features use environment variables in .env.local, which is intentionally ignored by Git.

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
OPENAI_API_KEY=
INTERNAL_SHARED_SECRET=

Never commit real .env* files or QA output containing secret values.

Project structure

app/                  Next.js routes and API handlers
components/           Shared UI and study components
content/              Seeded certification content
docs/                 Architecture and feature notes
lib/                  Local DB, mastery, quiz, sync, and recommendation logic
public-starter/       Barebones content used for the open-source snapshot
public/               Static assets, manifest, service worker, public docs
tests/                Vitest unit tests
e2e/                  Playwright smoke tests
supabase/             SQL migrations and edge functions

Status

This is an active build. The public app is usable, and the study loop, content coverage, sync behavior, competition flow, and agent connection story are still evolving.