DrillMap

DrillMap is a self-serve LSAT study-planning app. It turns a student's 7Sage analytics into a targeted Monday–Sunday drilling plan. Each new weekly schedule uses approved analytics and reported progress; a saved week stays fixed.

The schedule is generated by deterministic rules, not an LLM. Claude Vision is used only to extract structured data from a student-uploaded 7Sage screenshot; the student reviews that extraction before it becomes the current analytics snapshot.

Current state

The app stores its records in Postgres. See Postgres setup and tests for the local startup command, migrations, and database tests.

The core student workflow is implemented:

• Google sign-in and password sign-in with verified email (#230), with separate student and admin roles.
• Student signup, onboarding, profile editing, and a weekly dashboard
• A deterministic scheduling engine with coverage for its rules
• Append-only approved Analytics snapshots in Postgres
• One immutable adaptive weekly schedule per student/week, with activity check-ins that shape a future unsaved schedule
• A read-only admin view of each student's saved schedule and check-in state
• Public landing, legal, login, and signup pages

Billing is intentionally deferred. The tracked next feature is Issue #13: Stripe subscriptions, a seven-day trial, and the 7Sage referral discount.

Product and design sources

• PRODUCT.md defines the audience, product intent, and brand principles.
• DESIGN.md defines the DrillMap design system and the distinction between the public brand experience and the calmer authenticated product.
• .impeccable/design.json is the machine-readable design-system artifact generated for the current design iteration.
• AGENTS.md contains repository instructions for coding agents.

The original LSAT Rulebook and Engine Blueprint remain useful background references for the scheduling model:

1. The LSAT Rulebook
2. The Engine Blueprint

Key product decisions

• Analytics arrive through 7Sage screenshot upload; the app does not scrape 7Sage or share student credentials.
• The engine outputs a study-plan shopping list—question type, count, difficulty, and PT-130 side—not licensed LSAT question numbers.
• Students set capacity for each day and choose a preferred practice-test day. A practice-test review day follows each practice test, and the rest day moves off Wednesday when one of them takes it; the specification lists every case. Near-test weeks can contain two LawHub practice tests.
• Every drilling day has a daily minimum. The practice test, its review, a full section, or the daily minimum can exceed daily capacity; the day card shows the overage. Other drilling work stays within its fill limit.
• The adaptive-weekly-schedule-v2 policy saves reason sentences when it creates a schedule. Past weeks keep their planned work, capacities, and wording.
• AI does not decide the plan or change its rules.

Stack

• Next.js, TypeScript, React, and Tailwind CSS
• Postgres with Drizzle ORM
• Auth.js / NextAuth with credential and Google sign-in
• Anthropic API for screenshot analytics extraction
• Vercel for deployment

Uploaded analytics images are used in memory for extraction and are not stored by the application.

Local setup

Install Node.js 20.9 or later with npm. Local database setup needs either Docker with Compose or an existing Postgres 17 installation.

The Stage 1 pause on local data writes ended on October 8, 2026 after the separation, real-site, and local validation checks passed under the owner's evidence exception for unavailable old credentials. See issue #86 and the validation evidence (issue #86). The no-promotion rule remains in force. This does not approve launch.

The steps below describe setup for a new copy of the repository. Local work uses Postgres on your Mac with test data only. A loopback address accepts connections from this computer only. Never keep real-site credentials in local files. A credential is a secret that gives access, such as a password or an API key.

1. Install the app dependencies from the repository folder:

   npm install
   

2. Start local Postgres and apply the migrations. Follow Postgres setup and tests. It covers the Docker container and an existing Postgres 17 install.

   Migrations create the database tables. The migration command reads DATABASE_URL from the terminal environment, so use the explicit loopback value shown in that guide. It does not load .env.local.

3. Copy .env.example to .env.local for this new local setup:

   cp .env.example .env.local
   

   Keep DATABASE_URL at a loopback address. This connection string tells the app where to find the local database. Generate a new local Auth.js secret with the command in .env.example. Auth.js uses this secret to protect sign-in sessions. Put it in AUTH_SECRET.

   For Google sign-in, create a separate Google client for local work. Set its authorized origin to http://localhost:3000 and its only authorized redirect to http://localhost:3000/api/auth/callback/google. The redirect is where Google sends the browser after sign-in. Put this local client's ID and secret in AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET.

   Leave ANTHROPIC_API_KEY unset, including in your terminal environment. Keep SCREENSHOT_EXTRACTOR=fake. The fake extractor returns fixed rows for any uploaded screenshot and never calls Anthropic. Set it to fake-failure to see the "Couldn't read that screenshot" message: it hands the real model output checks a bad reply, which also writes one model_reply_refused entry in the security log. Without this setting, the app calls Anthropic when a key is set and shows that message when no key is set. Never set SCREENSHOT_EXTRACTOR on the real site. Admins can also use Sample analytics snapshots for their student side. An Admin reviews and approves each Sample analytics snapshot like an uploaded snapshot.

   For a real scan, use the testing key. It is the Anthropic key drillmap-testing in the drillmap-copy workspace, which has a $5 monthly spend limit. The copy site uses it as its ANTHROPIC_API_KEY. On your Mac, keep it in .env.local as ANTHROPIC_TEST_API_KEY. The app never reads that name, so local runs stay free. Pass it to a scan only on purpose. The owner shares the key through a password manager. Production keeps its own key.

Commands

npm run dev     # start the development server at http://localhost:3000
npm run dev:local  # apply migrations, then start at http://localhost:3000 with the fake screenshot reader
npm test        # run the scheduling-engine test suite
npm run lint    # run ESLint
npm run build   # create a production build
npm run start   # run a production build

Delete every student from the local database:

npm run reset:dev-data -- --yes

The reset removes all students and their Analytics snapshots, Weekly schedules, and Activity check-ins in one transaction. Accounts stay, so each person signs in and goes through onboarding again. Without --yes, it stops and names what it would delete. It refuses NODE_ENV=production before connecting.

The reset, make-admin, and db:migrate commands read postgres:// and postgresql:// strings only. They allow database hosts localhost, 127.0.0.1, and ::1. They check every host in the address and in the host and hostaddr query settings, even when the address has no host. They refuse remote hosts, other protocols, and missing or unreadable connection strings before connecting. No flag or environment setting bypasses this check.

The guard also allows exact copy-site hosts committed in scripts/copyDatabaseHosts.json. That list is empty until the owner verifies the copy's hosts. Add only full, lowercase host names for the copy, with no ports or credentials. Never add the real site's host, a wildcard, or a provider-wide suffix.

The guard refuses Postgres service settings because they can load connection settings from a separate file. See the Postgres connection documentation.

The v2 schedule specification records the current rules.