StudyFlow (Omni-Study)

StudyFlow — your study companion. A production-ready, self-hosted clone (functional superset) of the omni-study1.base44.app study-planning app, rebuilt as a single Next.js application you fully own: your database, your AI keys, your deployment.

Overview

The reference app is a study companion that keeps a student’s whole life in one place — but it lives behind a hosted platform login with no source access. StudyFlow rebuilds every surface (and fills in the ones the reference left empty) as an open codebase: twenty views from the daily dashboard to a focus timer, all wired to real CRUD persistence through Prisma/SQLite. Visual parity was measured from the live reference (computed styles, not eyeballing), and the places where the framework changed underneath — Tailwind v4’s engine differences chief among them — are documented and pinned by tests. Where the reference shows empty states, StudyFlow ships working features: an AI study assistant, a math solver that reads photographed problems, flashcard decks with a study mode, and a grade tracker with trend charts.

All 20 views (plus the login card, three mobile captures, seven dark-mode captures, the session-17 fresh-user evidence set — zero-data Analytics/Grade Tracker, the reference-measured empty-state hints, the Settings Profile/Notifications tabs, the mobile StudyGroups copy — the session-11 audit evidence pair, the session-12 accessibility evidence set — forced-colors renders, print pages, the focused skip link — and the session-13 resilience evidence set — the AI-chat failure rollback, the solver’s MIME guard toast, the remediated mobile drawer — and the session-14 hardening evidence set — the offline banner with the bounced-back composer, the AI rate-limit toast, the display-name guard) are in docs/screenshots/ — the standard 31 were refreshed after the session-11 theme-system remediation (node scripts/capture-studyflow.mjs); the S12 set via node scripts/capture-s12-evidence.mjs and the S13 set via node scripts/capture-s13-evidence.mjs, and the S14 set via node scripts/capture-s14-evidence.mjs, the S15 auth-flow set via node scripts/capture-s15-evidence.mjs (the login inline error, the signup form, the verify OTP screen, check-email, the calculator keyboard superset), and the S16 mobile set via node scripts/capture-s16-evidence.mjs (the auth sub-screens + the dashboard at 390×844 — the mobile-only responsive fixes; no default-media desktop visual changed in sessions 12–16; the prior pins are the byte-parity guarantee), the S17 fresh-user set via node scripts/capture-s17-evidence.mjs, and the S18 RUM set via node scripts/capture-s18-evidence.mjs (the beacon-live dashboard + mobile, the GET /api/rum aggregate, the un-instrumented login), and the S19 diagnostics set via node scripts/capture-s19-evidence.mjs (the /rum panel — desktop light + dark + mobile 390px), and the S20 v3 set via node scripts/capture-s20-evidence.mjs (the /rum panel with the per-card trend sparklines + the Export CSV action + the exported CSV head), and the S21 portability set via node scripts/capture-s21-evidence.mjs (the /export page — desktop light + dark + mobile 390px + the downloaded JSON envelope head), and the S22 boot-guard set via node scripts/capture-s22-evidence.mjs (the dev-server dashboard + /export + mobile 390px screenshots + the boot-guard evidence JSON — the negative spawn’s exit + message, the positive-control health, the dev-boot warn line), and the S23 import set via node scripts/capture-s23-evidence.mjs (the /export page with the Restore card — desktop light + dark + mobile 390px + the completed-import result state + the API round-trip evidence JSON — the first import’s summary, the idempotent re-import, the validation-error family, the rollback guard, the probe cleanup), and the S24 change-password set via node scripts/capture-s24-evidence.mjs (the Settings Profile tab with the Change password card — desktop light + dark + mobile 390px + the success-note state + the API round-trip evidence JSON — the guard family, the anon gate, the fresh-user rotation with the old-401/new-200 login pair, the session-survives proof, the demo restore), and the S25 account-deletion set via node scripts/capture-s25-evidence.mjs (the Settings Profile tab with the Danger zone card — desktop light + dark + mobile 390px + the revealed confirmation-form state + the API round-trip evidence JSON — the guard family, the anon gate, the fresh-user deletion with the DB-level cascade proof, the cleared-session me-401, the demo-intact proof), and the S26 email-change set via node scripts/capture-s26-evidence.mjs (the Settings Profile tab with the Email address card — desktop light + dark + mobile 390px + the success-note state with the live identity-block update + the API round-trip evidence JSON — the guard family incl. the same-email 400 + the duplicate 409, the anon gate, the fresh-user rotation with the DB-level emailVerified-stays-true proof + the old-401/new-200 login pair, the demo restore), and the S27 dark-sweep repair set (the before-state — MODE empty, 97 phantom flashbulbs + 7 phantom unreadable measured in LIGHT mode — and the after-state — MODE dark, all 20 views clean in real dark mode — with the guard’s negative-control exit, the restore proof, and the refreshed standing 31) in docs/screenshots/s27-dark-sweep-evidence.json, and the S28 connectivity-repair set (the before-state — the phantom “Login offline shows no/silent feedback” finding whose own measured bodyText contained the offline message — and the after-state — “Login offline announces the failure through the S15 inline alert (stays on the card, button recovered)” with findings 0 — with the reproduction probe, the negative-control exit, the gates, and the refreshed standing 31) in docs/screenshots/s28-connectivity-audit-evidence.json + the login-offline inline-alert capture s28-login-offline-inline-alert.png, and the session-29 doc-alignment refresh (the standing 31 re-captured from the remediated codebase — docs-only changes, zero app bytes moved) per docs/remediation-plan-session29.md, and the session-30 dependency-security evidence set (the bun-audit classification envelope with the two documented non-production advisories, the negative controls, the gates) in docs/screenshots/s30-dep-audit-evidence.json per docs/remediation-plan-session30.md

Key Features

Architecture

flowchart TB
    B["Browser — app shell (sidebar + view router)"] --> G["Next.js 16 route handlers /api/*"]
    G --> V["Zod validation"]
    V --> C["CRUD delegate factory (userId-scoped)"]
    C --> P[("Prisma 6 + SQLitedb/custom.db")]
    G --> AI["z-ai-web-dev-sdk(chat / math / vision)"]
    G --> S["HMAC cookie sessionsscrypt + rate limit"]

File Hierarchy

📂 src/
├── 📂 app/
│   ├── 📄 page.tsx              ← the whole app: auth gate + shell + view switcher
│   ├── 📄 login/page.tsx        ← reference-parity login card
│   ├── 📄 globals.css           ← Tailwind v4 @theme tokens + trap pins
│   └── 📂 api/                  ← auth, health, 16 entity CRUDs, AI, files, settings
├── 📂 components/
│   ├── 📂 ui/                   ← button, card, dialog, select, tabs, toast, …
│   ├── 📂 layout/               ← sidebar (fixed glass) + mobile drawer chrome
│   └── 📂 views/                ← the 20 view components + shared primitives
├── 📂 lib/
│   ├── 📄 db-path.ts            ← the DATABASE_URL contract (unit-tested)
│   ├── 📄 db.ts                 ← Prisma singleton with env resolution
│   ├── 📄 auth.ts               ← scrypt, HMAC sessions, rate limiter
│   ├── 📄 router.ts             ← 20-view ↔ PascalCase-path map
│   ├── 📄 data.ts               ← client cache + typed mutations
│   ├── 📄 calculator.ts         ← shunting-yard engine, GPA, converter
│   ├── 📄 theme.ts              ← 7 accents, RGB-triplet tokens
│   └── 📂 server/               ← http helpers + entity CRUD delegates
├── 📂 prisma/
│   ├── 📄 schema.prisma         ← 24 models; DATABASE PATH CONTRACT header
│   └── 📄 seed.ts               ← idempotent demo data
├── 📂 tests/
│   ├── 📄 *.test.ts             ← Vitest unit layer (834 tests)
│   └── 📂 e2e/                  ← Playwright specs (299 specs)
└── 📂 docs/
    ├── 📄 Tailwind-V4-Validation-Report.md  ← the five documented v3→v4 traps
    ├── 📄 remediation-plan.md   ← session-2 parity audit: evidence, fixes, non-gaps
    ├── 📄 remediation-plan-session3.md ← session-3 mobile-chrome & token audit
    ├── 📄 remediation-plan-session4.md ← session-4 text-metrics & login audit
    ├── 📄 remediation-plan-session5.md ← session-5 interactive-chrome & view-body audit
    ├── 📄 remediation-plan-session6.md ← session-6 populated-state & row-design audit
    ├── 📄 remediation-plan-session7.md ← session-7 lightly-probed-views & flashcards audit
    ├── 📄 remediation-plan-session8.md ← session-8 deep-chrome/layout audit (16 gap families)
    ├── 📄 remediation-plan-session9.md ← session-9 data-state/chart-axes/icon audit (19 gap families)
    ├── 📄 remediation-plan-session10.md ← session-10 dark-mode consistency audit (the @theme inline token trap + 6 tint families)
    ├── 📄 remediation-plan-session11.md ← session-11 theme-system audit (pre-paint boot script + System tracking + accent-dark re-themes)
    ├── 📄 remediation-plan-session12.md ← session-12 accessibility audit (forced-colors state restoration + print + skip link + reduced-motion)
    ├── 📄 remediation-plan-session13.md ← session-13 resilience audit (AI failure states + upload edge cases; data-volume stress verified green)
    ├── 📄 remediation-plan-session14.md ← session-14 hardening audit (connectivity UX + settings guards + security headers/limits + AI live regions)
    ├── 📄 remediation-plan-session15.md ← session-15 auth-flow audit (inline errors + signup/verify/forgot/reset + calculator keyboard superset)
    ├── 📄 remediation-plan-session16.md ← session-16 CWV/mobile-geometry audit (load-stability pre-warm + responsive auth sub-screens + fresh copy sweep)
    ├── 📂 screenshots/          ← dev-server captures of every view (light + dark)
    └── 📄 DEPLOYMENT.md         ← production notes

Quick Start

Requires Bun ≥ 1.3 (or npm with Node ≥ 22 — swap bun for npx/npm run).

git clone https://github.com/nordeim/omni-study.git
cd omni-study
bun install

# Database — .env ships with DATABASE_URL="file:../db/custom.db";
# db/ lives at the repo root (git-ignored, recreated by these two commands):
bun run db:push
bun run db:seed

bun run dev

Verify setup:

1. curl http://localhost:3000/api/health → {"status":"ok","db":"up","app":"studyflow"}
2. Open → redirects to /login
3. Sign in with the demo account — [email protected] / Demo1234! — you land on the dashboard with seeded subjects, tasks, exams, notes, decks and grades.

Environment Variables

Copy .env.example to .env (the defaults above already work locally):

Testing

bun run test        # Vitest — 834 unit tests (router, theme, date, calculator incl. mapPhysicalKey, auth incl. the AI rate-limit budget + the verification/reset seams, validation incl. verify/forgot/reset schemas + the S24 change-password rotation seam + the S25 deletion seam + the S26 email-rotation seam, db-path, site-url, theme-cache + boot-script contract + content-disposition + api-timeout + the offline transport-error mapping, rum-diagnostics — the CWV thresholds/panel display seam + the S20 sparkline geometry + the CSV builder, data-export — the S21 envelope/manifest/secret-guard seam, env-check — the S22 AUTH_SECRET boot-guard seam, data-import — the S23 envelope-validation/FK-pre-emption/folders-topo-sort seam, dep-audit — the S30 bun-audit parser/classifier seam, dev-preflight — the S31 dev-server boot-stability classifier seam, suite-verdict — the S32 standing-suite verdict seam [the anti-phantom shape-error guard + the three documented non-gap signatures] + the S33 mobile-sweep classifier [the light-mode 390×844 drawer-navigation sweep] + the S34 midband-sweep classifier [the light-mode 768×1024 drawer-navigation sweep — the md breakpoint, the 391–1023px band's representative width, with the chrome vehicle-contract class] + the S35 landscape-sweep classifier [the light-mode 844×390 phone-landscape drawer-navigation sweep — the HEIGHT axis the standing surface never varied, with the per-view heading-clearance key + the drawerNavScrollable short-viewport contract class] + the S36 dark-mobile-sweep classifier [the dark-mode 390×844 drawer-navigation sweep — the MODE axis at the mobile viewport the standing surface never varied, with the per-view flashbulbs/unreadable detector keys + the drawer dark record + the INDEPENDENT dark-detection counting] + the S37 accent-light-sweep classifier [the accent × light 390×844 sweep — the ACCENT axis in LIGHT mode the standing surface never varied, with the ALL-ACCENTS guard + the per-accent applied self-verification + the three signature-strict non-gap exemptions (the CTA-face, the calendar adjacent-month slate-300 days re-verified live on the reference, the yellow-500 priority-pill vocabulary)] + the S38 accent-dark-sweep classifier rebuild [the accent × dark MOBILE 20-view matrix — the pre-S38 mobile pass swept only 6 views; the ALL-ACCENTS + ALL-VIEWS + drawer-present anti-phantom guards, every view recorded explicitly on both surfaces, the per-accent applied self-verification, the mode/mobileViewport contracts, and the mobile scrollWidth overflow class] + the S39 accent-midband-sweep classifier [the accent × mid-band 768×1024 drawer-navigation sweep — the mid-band × accent cell never probed + the navigation-interaction gap: the accent sweeps navigate by direct goto, so the drawer's active-link tint was only ever read on the Dashboard link; with the ALL-ACCENTS + ALL-VIEWS + drawer-present guards, the vehicle-contract class, and the TWO interaction finding classes (the tint rot — activeTint "none", the S8 no-var class; the active-state mismatch — activeLabel ≠ the view)] + the S40 accent-landscape-sweep classifier [the accent × landscape 844×390 drawer-navigation sweep — the landscape × accent cell never probed (landscape-sweep is light+violet only) and the S39 interaction proof extended to the SHORT viewport, with the S35 short-viewport contracts (headingClearance + drawerNavScrollable) folded into the S39 accent shape] + the S41 accent-desktop-sweep classifier [the desktop light-accent sidebar-navigation sweep at 1280×800 — the documented S37 bracketed non-gap: accent-dark covers 1280 dark only, and the SIDEBAR-vehicle active-link tint was verified at ZERO views, ZERO accents, in either mode; with the INVERTED vehicle contract (sidebarVisible true + hamburgerVisible false), the sidebar-own scroll contract (sidebarNavScrollable at 800 height), the per-view headingOffset key, and the interaction finding classes on the DESKTOP vehicle]) + the S42 accent-volume-sweep classifier [the data-volume × dark × accent stress — the S13 volume profile (300/200/250) swept through the theme space's dark-accent half: the volume counts EXACT at the seam (a seed-volume envelope is its own rot class), the ALL-ACCENTS + ALL-VIEWS guards (the 7 volume-affected views — the S13 set), the per-view S13 measurement family (nodes/mainNodes/longTaskTotal ≤ 1500ms/clickLatencyMs ≤ 1500ms), the S38 dark detector family (flashbulbs always findings; the CTA-face exemption ONLY — the light-mode calendar-day + yellow-pill exemptions do NOT apply in dark), the interaction evidence in DARK (the never-read sidebar-tint cell), and the /api/tasks ≤ 500KB B1 bound]
bun run build       # REQUIRED before e2e — the suite boots the standalone server
bun run test:e2e    # Playwright — 299 specs against the production build on :3100

E2E notes: the suite pushes and seeds an isolated db/e2e.db (never touches custom.db), signs the demo user in once via a setup project (the login endpoints are rate-limited — 10 attempts/IP/15 min), and asserts the reference-measured design pins (sidebar geometry, v3 shadow-sm, canvas gradient, view-title model, stat-card text metrics, empty-state design, brand-gradient stops, login chrome, the session-5 interactive-chrome pins, the session-6 populated-row pins, the session-7 flashcards/timetable/analytics/dialog pins, the session-8 deep-chrome/layout pins, the session-9 data-state/chart-axes pins, the session-10 dark-mode consistency pins — the shadcn token utilities, banner/amber/clock/today/chart dark re-themes, the dark mobile drawer, and a light-mode byte-parity regression guard — the session-11 theme-system pins — pre-paint dark application, the dark-OS login, runtime System tracking, the theme-color meta, the accent-surface dark re-themes, print emulation, and a light regression guard — the session-12 accessibility pins — forced-colors state outlines + the bold active nav + the slider gradient, the skip link’s Tab order/focus/Enter landing, the beforeprint/afterprint light-forcing, print-color-adjust: exact on the essential surfaces, the timetable print width reset, reduced-motion collapse, and a light regression guard — the session-13 resilience pins — the AI-chat failure rollback + recovery, the solver’s client-side MIME guard with zero outbound requests, the nameless-upload rejection, and the RFC 5987 download header — and the session-14 hardening pins — the offline banner’s appear/disappear + online absence (byte-parity guard), the human offline toast, the whitespace display-name 400 + trim-on-save, the AI-route per-user rate limit (20 then 429 with Retry-After), the download nosniff + private no-store headers, and the AI transcript/solver aria-live regions — and the session-15 auth-flow pins — the inline login-error alert with its measured chrome, the signup form’s reference shape, the register→verify→signed-in journey via the surfaced code, the unverified-login gate, the forgot→check-email→reset-link→new-password journey, and the calculator’s physical-keyboard superset including the form-field guard — and the session-22 boot-guard pins — the standalone production server spawned WITHOUT AUTH_SECRET exits non-zero with the actionable message (the openssl rand -hex 32 remedy), and the positive control: the suite’s own properly-configured boot answering /api/health — and the session-24 change-password pins — the anon 401 gate, the wrong-current/same-password/short-new 400 family (pre-write: the demo hash untouched), and the fresh-user rotation round-trip: register → sign in → the panel rotates → the old password login 401 → the new password login 200 → the session survives — and the session-25 account-deletion pins — the anon 401 gate, the wrong-password/wrong-confirmation/short-password 400 family (pre-write: the demo account untouched, still signing in), and the fresh-user terminal journey: register → sign in through the UI → the panel reveals the Danger zone form → the wrong-word early inline error → the deletion → the redirect to /login → the old-credentials login 401 → the cleared session’s me 401 — and the session-26 email-change pins — the anon 401 gate, the wrong-password/mismatched-confirm/short-password/same-email 400 family + the duplicate-email 409 (pre-write: the demo account untouched, still signing in), and the fresh-user identity rotation: register → sign in through the UI → the panel’s Email address card → the mismatched-confirm early inline error → the change → the success note + the identity block showing the NEW email (the live store update, both surfaces) → the session survives me 200 with the new email → the old-email login 401 → the new-email login 200). Full gate order: lint → typecheck → test → build → test:e2e.

API Reference

All endpoints are same-origin JSON; sessions ride the sf_session cookie. 🔒 = requires authentication.

Design System

Measured from the live reference (see docs/Tailwind-V4-Validation-Report.md for the full trap log):

Six accent themes × Light/Dark/System × 24 emoji avatars, all persisted to the user record.

Deployment

The app builds to a standalone server (output: "standalone" in next.config.ts):

bun run build
bun run start        # NODE_ENV=production, serves .next/standalone

For production use an absolute DATABASE_URL (see docs/DEPLOYMENT.md §4) and set AUTH_SECRET. Deploy keys never live in the repo — pushes use the docs/ssh_git_wrapper_v3.py wrapper (see docs/how-to-git-push-using-ssh-wrapper_SKILL.md).

Troubleshooting

Contributing

The verification gate before any push: bun run lint && bun run typecheck && bun run test && bun run build && bun run test:e2e. Conventions that differ from defaults: Tailwind v4 CSS-first (no tailwind.config.js — theme lives in src/app/globals.css @theme); gap-* layout only (never space-y/x with margin-carrying children); Zustand stores over Context; every API payload through its Zod schema in src/lib/validation.ts; z-ai-web-dev-sdk imported only inside route handlers.

Project Status

No license file is present in this repository; treat the code as proprietary to the repo owner.