CaseForge

A case-management app for people representing themselves in North Carolina civil court — small claims matters heard by a magistrate, and other civil matters filed with the clerk.

The user has no lawyer, has never done this before, and is afraid of getting it wrong. Everything here is built for that person.

The rule this codebase is organized around

CaseForge organizes information. It does not decide anything.

The user enters and confirms every fact. The software stores, formats, reminds, and displays. The moment the software applies a legal rule to the user's facts, it is practicing law without a license.

We do	We never do
Store the date the user entered	Calculate a deadline from a legal rule
Show the AOC form they picked	Tell them which form they need
Save what they typed in a field	Decide what belongs in the field
Read a date off an uploaded document	Interpret what it means for their case
Organize their exhibits	Tell them which exhibits help

CaseForge also never files anything with the court.

How the rule is enforced in code

Confirm-before-save is architecture, not a UI convention. Three things hold it up:

1. Confirmed<T> (lib/domain/confirmation.ts) — every time-sensitive value in the model is wrapped in a type that cannot be constructed without a user id and a stated source (user-entered, or read-from-document with the document id it was read off).

2. assertWritable (lib/db/guard.ts) — the data layer re-checks at runtime, on every write, that each registered time-sensitive field holds a real confirmation. Types disappear at compile time; this does not. A bug in a form, a route, or a future AI extractor cannot quietly write a date.

3. Proposals are a separate table — anything CaseForge thinks it read lives in proposals, is never rendered as part of the case record, and can only leave that table through a user confirming or dismissing it.

Adding a dated or legally-consequential field to the model means registering it in TIME_SENSITIVE_FIELDS. npm test covers the guard, including forged confirmations.

The forms rule follows from the same principle

Case types live in a registry (lib/domain/case-types.ts), and each entry declares whether the Administrative Office of the Courts actually publishes a fill-in complaint form for it:

• Small claims (CVM) — AOC publishes a form complaint for each: money owed, summary ejectment, recovery of personal property, possessory lien on a motor vehicle, vacation rental ejectment, expedited removal.
• Civil (CV) — AOC publishes form complaints only for a specific list of statutory proceedings: domestic violence protective orders, no-contact orders (stalking, workplace violence, trafficking), and underage marriage authorization.
• Everything else — contract disputes, injury, property damage — has no fill-in complaint form. AOC gives you a Civil Summons and you draft the complaint yourself.

Where complaintForm is null, the app says so plainly and stops. It does not help the user assemble a complaint from their answers, because turning a person's situation into a legal document is authoring a legal document. The organizing half of the product — vault, timeline, evidence, hearing prep — works for every case type regardless.

Form numbers were read from the AOC statewide forms search on the date in FORMS_VERIFIED_ON. Re-check before relying on them; forms get revised.

Every date in the app goes through one gate

All dates live on TimelineEvent, whose date is a Confirmed<string>. There is no second path. Reminders are only ever attached to a confirmed date.

What is built

• Auth — sign-in, and the "not a law firm" acknowledgement at signup.
• Case setup — guided intake, one question per screen, plain English, with a visible checklist. Case types are grouped as small claims vs. other civil matters, and the app states up front whether an official form exists for the type chosen. The review screen is the confirmation gate: nothing is written until the user says the details are correct.
• Document vault — upload a photo or PDF, and the document lands unlabeled. CaseForge then asks what it is. Only after the user answers does a label or a date get stored, tagged with the document it came from.
• Case overview — what is coming up, with provenance on every date, and a done/left checklist.
• Timeline — past and upcoming split around today, add a date by hand behind a confirmation tick, correct a date (which re-mints the confirmation rather than editing the old one), and per-date reminders.
• Public landing page — what the product is, and an equally prominent statement of what it will never do. Plus pricing, and example case files.
• Hearing prep — the person's case as an ordered list of points in their own words, either as the one filing ("what happened") or the one answering ("they say / my response", following the complaint they were served). Documents from the vault attach to points and are lettered as exhibits in the order the points use them — letters are worked out, never stored, so reordering can't leave them out of step. Prints as one packet: cover, points, exhibit list, then each exhibit on its own page.
• Put my story in order (needs an API key) — the person types their account and the model returns their events in order, in their words, with anything it could not place returned as a question. The result is a draft in the browser and is never saved until the person edits and saves it.
• Reading dates off documents (needs an API key) — on upload, the model proposes what the document is and which dates are printed on it, each with the exact words it read. The person confirms or corrects each one. A value they kept carries its excerpt as provenance; a value they changed is recorded as theirs. HEIC photos and images over 5 MB skip reading and go to the manual form.
• Court forms — AOC-CVM-200, 201 and 202, the official PDFs from nccourts.gov, with every field mapped and labelled in the form's own words. Names, addresses, county and file number carry across from the case; amounts, reasons, dates and every check box are left to the person. Downloads as the official form, still fillable. Tests check the mapping against the real PDFs field by field.
• Business lookup — guided steps to the NC Secretary of State's public registry. That site blocks automated requests, so the person searches it in their own browser and copies the legal name and registered agent across.

Reminders are in-app only. A user can flag a date and see it on their timeline, but nothing is delivered by email or text — there is no provider wired up. The timeline says so out loud rather than implying a court date will be chased down for the user.

AI features switch themselves off without a key. With no ANTHROPIC_API_KEY, the story organizer is hidden and uploads go straight to the manual form. Nothing else changes. Model calls use claude-opus-5 with server-side refusal fallbacks enabled.

Connecting Supabase

The app runs with no database at all. Set these four variables and it switches over to Supabase for sign-in, data and uploaded files — no code changes.

NEXT_PUBLIC_SUPABASE_URL=            # Project Settings -> API
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=  # the publishable (or anon) key
SUPABASE_SECRET_KEY=                 # the secret (or service role) key
CASEFORGE_PREVIEW=0

On Vercel these go in Project Settings -> Environment Variables. The secret key is server-only: never prefix it with NEXT_PUBLIC_.

In the Supabase project, once:

1. SQL Editor -> New query -> paste supabase/schema.sql -> Run. This creates the tables, the row-level security policies, the private case-documents bucket, and the trigger that makes a profile when someone signs up.
2. Authentication -> URL Configuration -> set the Site URL to the live site, and add these Redirect URLs:
   • https://<the live domain>/auth/callback
   • http://localhost:3100/auth/callback (for local development)

Sign-in is by emailed link — no passwords are stored anywhere. Supabase sends the email; its default template is fine to start with.

What switching on changes: CASEFORGE_PREVIEW stops closing sign-up as soon as Supabase is configured, so accounts open the moment the keys are set. Expect to migrate nothing — the local .data file is development data only.

Getting started

npm install
npm run dev

npm test        # the confirm-before-save guard, and the county table
npm run typecheck

Deploying this yourself

A fresh clone builds with no configuration:

git clone <this repo>
cd caseforge
npm ci
npm run build

To put it online, import the repository at vercel.com/new and press Deploy. vercel.json already sets CASEFORGE_PREVIEW=1, which closes sign-up with a plain explanation — the file-backed store does not persist on serverless, so accounts cannot work until a real database is wired in. Nothing else needs configuring.

Taking ownership of it

Everything is in this repository; there is no state held anywhere else yet. To run it under your own accounts:

1. Create a GitHub account, or better an organization — free, and ownership is not then tied to one person's login.
2. Either have the repository transferred to you (Settings → General → Danger Zone → Transfer ownership), or create an empty repository and have it pushed to you. Whoever is working on it should be added back as a collaborator immediately after — the previous owner loses access the moment you accept.
3. Create a Vercel account, install its GitHub app, and import the repository. That gives you your own deployment and your own URL.
4. The previous owner deletes their Vercel project, so the same code is not deployed twice.

Do this before anyone real signs up. Once the app holds users' court documents and takes payments, moving it stops being an administrative task: a Stripe account cannot be transferred between people, and a database of other people's legal documents is not a file you can simply hand over.

Environment variables

See .env.example. There are only two today, both optional locally. Anything added later — a database URL, an API key, a Stripe secret — belongs there as a documented placeholder, never committed with a real value.

Before this touches a real user

This is a development build. These are blocking, not nice-to-have:

• Auth is a stub. lib/auth stores a plain user id in an unsigned cookie. Anyone who can set a cookie can act as any user. Replace it with a real provider — the getSession / requireSession / signIn / signOut interface is the seam, and no page or action should need to change.
• Storage is a stub. lib/storage writes to the local filesystem and lib/db writes a JSON file. Case documents are sensitive; real storage needs encryption at rest, backups, and a deletion path.
• County dollar limits are unverified. These are small-claims context only, and the app now shows them only on a small claims matter. All 100 counties are listed in lib/domain/counties.ts with limitCents: null on purpose. Each county's chief district court judge sets a local limit under the $10,000 statewide ceiling. Populate these only from nccourts.gov, and set verifiedOn when you do. Until then the app says plainly that it does not know the limit, which is true, rather than showing a number we invented.
• Only three forms can be filled. The small claims complaints are hosted; the civil forms in the case type registry (protective orders, no-contact orders) point to nccourts.gov instead. Forms get revised — re-check each PDF's revision against nccourts.gov before launch, and when AOC publishes a new one.
• Uploaded documents go to Anthropic when reading is on. The privacy policy has to say so, and people need to know before they upload. Worth checking the data-retention terms on the API account used.
• Have an NC lawyer review the product. North Carolina regulates websites that produce legal documents from a consumer's answers (G.S. 84-2.2). Filling the court's own forms with the person's own words may or may not fall under it. That is a question for an NC-licensed lawyer, not for this README.
• Reminder delivery does not exist. See above. Until it does, a user could reasonably believe they will be told about a hearing and not be.
• Protective-order cases need a safety review before launch. The registry now includes domestic violence and stalking matters. An app that stores a survivor's documents and hearing dates behind a weak login is a safety problem, not just a security one. That needs its own design pass.

One line we drew deliberately

CaseForge shows a county's dollar limit as information. It does not compare the user's claim against it, and does not tell them whether their case belongs in small claims court. That comparison is applying a legal rule to their facts. The same reasoning keeps the app from picking a case type, picking a form, or computing a deadline.