Project Info

Crux — Built to Prepare

Inspiration

Most study tools assume you have weeks. Real students often have hours. LETS BE HONEST HERE , literally everyone i know from my college start preparing 1-2 days or even 12 hours before exam 😭🥀 , but we dont need a platform whcih builds us roadmap to study which is oriented with the thought we have lots of time to study so a big elaborated roadmap , thats why what we are building is for students or anyone with a deadline and a problem in mind we are having custom agentic harness building out perfect roadmaps for the students after testing their capabilities to get them the top marks within 12 hrs Before an exam, the problem is rarely “not enough content.” It’s decision paralysis: notes in PDFs, slides in folders, past papers in chats, and no clear answer to the only question that matters— What deserves the next 25 minutes? Crux was built for that moment. Not another chatbot tutor that invents answers—a deadline-first workspace that reads your materials and turns them into an explainable study plan.

What it does

Crux is a deadline-aware study workspace. The core loop: Create a workspace with an exam date and constraints Upload sources — syllabus, lecture slides, notes, past papers (PDF, DOCX, PPTX, TXT, Markdown) Extract a Study Map — topics, dependencies, and cited source evidence Calibrate confidence — a fast check of what you already know Plan a mission — a realistic time-budgeted sequence of learn / practice / review / skip Study and prove it stuck — source-grounded briefs, questions, and a review desk Crux is opinionated on purpose. Every screen pushes toward one next action, with evidence you can inspect—not a black box grade prediction.

How we built it

Product stack Next.js 15 + React 19 for the app shell and study surfaces Supabase for Postgres, auth-ready architecture, and private file storage Drizzle ORM for schema and migrations Inngest for async document ingestion and extraction React Flow for the interactive Study Map TanStack Query + Zustand for client state AI architecture Deterministic topic inference and mission planning stay explainable Optional generation runs through a bounded harness: retrieve evidence → pack context → generate → validate → cite Students can bring their own OpenAI key (Responses API) and select GPT-5.6 for source-grounded study briefs and concept guides Built with Codex + GPT-5.6 Codex accelerated the end-to-end product: ingestion pipeline, roadmap extraction, mission planner, Study Map UI, API routes, and review flows GPT-5.6 is the generation model for study briefs—grounded in uploaded excerpts, not generic textbook regurgitation Key product decisions stayed human: deadline-first UX, citation-first answers, and “next action” clarity over chat-first UI

Challenges we ran into

Trust vs. speed — students need a map in minutes, but incomplete uploads can’t pretend to be complete. We surface uncertainty instead of hiding it. Grounding — AI answers must point back to the student’s sources; unconstrained tutoring was a non-goal. Planning under pressure — optimizing for marks-per-minute without feeling harsh or opaque. Real document mess — PDFs, slides, scanned notes, and pasted text all behave differently; extraction + OCR had to stay resilient.

Accomplishments we're proud of

A working spine from upload → extract → map → calibrate → plan → study → practice → review Source-cited topic evidence, not floating flashcards An interactive Study Map that makes dependencies and progress visible A BYOK path so students can use GPT-5.6 without Crux holding their keys in plaintext A product thesis that stayed narrow: ruthless next moves under a deadline

What we learned

Under exam pressure, clarity beats features. One obvious next action beats a dashboard of options. Separating retrieval / planning / generation keeps the system honest when the model is wrong. Codex is strongest when the product loop is already clear—then it compresses implementation time without diluting the thesis. Students trust systems that show their work: citations, confidence, and “why this topic now.”

What's next

Deeper past-paper pattern clustering (what repeats, what converts to marks) Stronger last-day revision modes (including audio briefs) Collaborative workspaces for study groups Better OCR and image-heavy notes support Tighter GPT-5.6 study modes: trap detection, formula recall, and timed practice sets

Crux

Deadline-first study workspace. Upload the materials you already have (syllabus, notes, PYQs), get a sourced topic map, calibrate what you know, then plan and clear units before the exam.

Create workspace → Upload sources (+ PYQ) → Extract map → Calibrate → Plan → Study → Questions → Clearance → Deadline

Live product surface: crux-snowy.vercel.app

Why Crux

Most study tools optimize for long courses. Crux optimizes for the last stretch:

Deadline-aware planning around the hours you can protect
Source-backed notes and briefs (citations, not free-floating chat)
PYQ-aware clearance so practice tracks what the paper actually asks
Study Map for pathing units, Clearance for proving mastery, optional oral viva / Last Lap audio when configured

Crux is not “an AI that knows everything.” It helps you decide what deserves the next block of time, why, and how to prove it stuck.

Stack

Layer	Choice
App	Next.js 15 (App Router), React 19, TypeScript
UI	Tailwind, local craft components, React Flow (Study Map)
Data	Postgres via Drizzle ORM, Supabase Auth + Storage
Jobs	Inngest (optional locally; inline ingest without a worker)
AI (optional)	Fireworks / Bedrock / BYOK OpenAI & Anthropic, ElevenLabs TTS

Quick start

Requirements: Node.js 20+, npm.

UI-only preview

Enough for marketing pages and most screens without a database:

git clone https://github.com/nothariharan/crux.git
cd crux
npm install
npm run dev

Open http://localhost:3000.

Full study loop

You need your own Supabase project (database + private Storage bucket).

Create a Supabase project and a private Storage bucket named resources.
Copy env template and fill required keys:

cp .env.example .env   # macOS / Linux
# Copy-Item .env.example .env   # Windows PowerShell

Minimum required:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
DATABASE_URL

Apply schema and seed the local demo user:

npm run db:push
npm run db:seed
npm run dev

Smoke path:
1. /onboarding — create a workspace
2. Upload syllabus/notes + previous papers (PYQ)
3. Wait until sources are Ready
4. Calibrate → build a mission → open Study Map / Study / Questions / Clearance

Auth stays off for local single-user testing unless ENABLE_AUTH=true. Never commit .env.

See .env.example for optional AI, OCR, Inngest, and demo flags.

Scripts

Command	Purpose
`npm run dev`	Next.js development server
`npm run build` / `npm start`	Production build & serve
`npm run lint`	ESLint (zero warnings)
`npm run typecheck`	TypeScript `--noEmit`
`npm test`	Unit tests (Node test runner + tsx)
`npm run db:push`	Push Drizzle schema + apply Supabase RLS helpers
`npm run db:migrate`	Run SQL migrations + RLS
`npm run db:seed`	Seed local demo user
`npm run db:baseline -- --confirm`	One-time migration journal baseline for legacy DBs

Optional Inngest worker:

npx inngest-cli@latest dev

Without INNGEST_EVENT_KEY, uploads still process inline in the Next process.

Product map

Route	Role
`/`	Landing
`/onboarding`	Mission, time boundary, sources + PYQ, calibration
`/workspace`	Desk: sources, mission, quick calibration
`/study-map`	Interactive roadmap (React Flow, lazy-loaded)
`/study`	Source-backed notes / briefs per topic
`/questions`	PYQ practice + active recall
`/review`	Clearance quizzes, oral assessment, reports
`/settings`	Workspace, AI keys, exports, optional demo prep

Security notes (before going public)

Secrets live only in .env / host env vars — see SECURITY.md.
Demo prep (fast-forward mastery) is off by default. Enable only in trusted demos:
```
ENABLE_DEMO_PREP=true
NEXT_PUBLIC_ENABLE_DEMO_PREP=true
```
Leave both false on public production.
Workspace “public share” exposes metadata for link access; keep it off unless you intend that.
If ENABLE_AUTH=true, configure Supabase Auth redirect URLs for your domain (e.g. https://your-app.vercel.app/auth/callback).

Documentation

Doc	Contents
docs/README.md	Index of planning & design docs
docs/PRD.md	Product requirements (historical name: LastLap)
docs/TECHNICAL-DESIGN.md	Architecture & data model
docs/UX-SPEC.md	UX specification
docs/AI-HARNESS.md	Generation / grounding notes
CONTRIBUTING.md	How to contribute
SECURITY.md	Vulnerability reporting

Contributing

Issues and PRs are welcome. Please read CONTRIBUTING.md before opening a large change.

npm run lint && npm run typecheck && npm test

License

MIT — see LICENSE.

Disclaimer

Crux helps you organize and practice from your materials. It does not guarantee exam outcomes. Treat model output as assistive; verify against your syllabus and past papers.

Analysis

Compare with all teams

View

Metric

nothariharan
93
Narain Karti
1

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

CSSIn code
HTMLIn code
Next.jsIn code
ReactIn code
SQLIn code
SupabaseIn code
Tailwind CSSIn code
TypeScriptIn code
AWSClaimed
OpenAIClaimed
PostgreSQLClaimed

8 of 11 appear in the indexed code. 3 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

943 KB

Source files

188

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.