Case study 02

Contract Explainer

A web app that reads a contract or policy section by section, explains each part in plain English, and puts the sections that deserve the most attention at the top.

The idea

Most people sign leases, loans and terms of service without reading them, because the documents are long and written for lawyers. I review contracts in my day job, so I know how much a single clause can matter. I wanted a tool that tells an ordinary reader what each section says and where to look first, without pretending to be a lawyer.

What it does

• Accepts pasted text, or a PDF or text file that is read inside the visitor's own browser.
• Splits the document into sections and sends each one to an AI model with the document type and the visitor's state.
• Returns a plain-English explanation, a concern level, a question to ask, and a pointer to where the rule can be verified.
• Builds a "What matters most" summary that lists the high-concern sections and tucks the minor ones away.

Decisions I made

• Prototype in Python, ship in JavaScript. I learned the AI call and worked out the prompt in a Python script on my own machine. For production I ported the logic to a serverless function, because that is what my host runs.
• The key never reaches the browser. The page talks to my function, and the function talks to the AI. The API key lives in an environment variable on the server and appears in no file a visitor can load.
• One section per request. Reviewing a whole document in one call took about a minute and would have hit the function's time limit. Sending sections one at a time keeps every request short and lets results appear as they finish.
• Make the AI's answer readable by code. Every answer starts with a fixed line giving the concern level. That one line drives the badges, the sort order and the summary.
• Explain, do not advise. The prompt forbids telling anyone whether to sign and forbids citing statute numbers from memory. The app points to official sources and requires consent to its terms before a review runs.
• Do not keep the documents. Files are read in the browser and the text is not stored in any database of mine. The only thing I count is how many sections were reviewed each day.
• Limits at every layer. A document length cap, a section cap, a per-visitor rate limit, a daily cap across all visitors, and a prepaid balance with a monthly ceiling. A free tool with a paid API behind it needs all of them.

What went wrong, and how I fixed it

• A false alarm inside a word. The first scanner looked for the phrase "as is" and found it inside "was issued". I changed the match so a phrase only counts when it starts at the beginning of a word.
• Two harsh clauses with no warning words. A test loan said the whole balance came due after one late payment, and that the borrower gave up joining lawsuits. Neither used a word on my list, so both were skipped. No list fixes that, so I redesigned: the AI now reads every section and the keyword scan is only a hint.
• A flag on good news. "There is no late fee" was flagged for containing "late fee". The same redesign solved it, because the model reads the meaning.
• A report nobody would finish. On a real terms of service, 24 of 26 sections came back with some level of concern. That is as much reading as the original. The summary panel and the collapsed group of minor sections came out of that test.
• Documents that tell the AI what to do. A pasted document could contain instructions aimed at the model. The section text is now fenced off and the model is told to treat it as material to explain.
• Headings lost in the split. Short lines such as a clause title were being dropped. The splitter now attaches a short line to the paragraph that follows it.

How I built it

I built this with an AI assistant as my tutor, over fourteen working sessions. Each session added one layer: a keyword scanner, a first API call, a prompt, error handling, testing, the page, the server function, cost controls, the summary, and the policies. I ran every piece, broke it on purpose, and tested it against a document built to trip it before moving on.

What is next

Looking up verified state statutes and showing the official source beside each explanation, so the app can say what the rule is and link to it. After that, a mobile version that reads a paper contract through the phone's camera.

← Back to all work