ClearForm

Inspiration

Official paperwork decides whether people keep their benefits, pay the right amount, or show up on time, and it's written in language that's hard for almost everyone. It's hardest for people reading in a second language, older people, and families helping each other over the phone. One missed line like "within 30 days of this notice" can mean late fees, a lost benefit, or a bill sent to collections. And scammers copy the same official tone, so a fake "final notice" can look as real as a true one.

What it does

Take a photo, screenshot, or PDF of a bill, form, or official letter (up to 6 pages) and choose one of 16 languages. ClearForm explains it at about a 6th-grade reading level:

• How urgent it is: "Act now" or "Act soon", the nearest deadline, and how many days are left.
• What to do: a checklist of steps, with how and when to do each one.
• Help filling in forms: for every blank, what it's asking, what to write, where to find that information, a made-up example, and whether it's required.
• What to watch out for: penalties, late fees, rights and help the document mentions (payment plans, financial assistance, free interpreters), unclear parts, and signs of a scam.
• Proof from the page: every point has a "Where it says this" link that shows the exact words from the document, so you can check it yourself.
• Follow-up questions in your own language, answered from the document.
• Take it with you: read it aloud, copy the checklist, add upcoming deadlines to your calendar, or print it.

The whole interface switches to the chosen language, and Arabic and Urdu read right to left.

How we built it

• Next.js 16, React 19, and TypeScript: one page with three states (upload, progress, and the explanation).
• Gemini through the Gemini API (Google AI Studio): photos and PDFs go straight to the model. A Zod schema, converted to JSON Schema, makes Gemini return the same structure every time. That lets the interface show urgency, steps, form fields, and warnings as real components instead of a wall of text.
• Faithful by design: the prompt requires an exact quote from the document for every point, exact dates only when they can be worked out, and "not stated" instead of guesses. It shows only the last four digits of ID and account numbers, never copies what someone has already filled in, and treats instructions written inside the document as content, never as commands.
• Streaming: the server streams progress (reading, thinking, writing) and the answer as NDJSON. Gemini's thought summaries drive the "thinking" step, so the progress bar is real.
• Built for real-world limits: when a model is overloaded, out of free quota, or hasn't started answering within 15 seconds, the request moves to the next Gemini model. Explanations can even start over partway through, because nothing is shown until the answer is complete.
• Private by default: no database and no accounts. Uploads and explanations stay in the browser tab.
• Tested without a key: 29 tests run the real Gemini SDK against a local mock of the streaming API to check requests, blocked and cut-off answers, retries, quota errors, and model fallback.

Challenges we ran into

• Trust. An explanation that's confidently wrong about a deadline is worse than none. Requiring an exact quote for every point, and showing it on demand, made the output checkable.
• Free-tier reality. The newest Gemini models sometimes hung under heavy demand, and each model allows only 20 free requests a day. We added automatic fallback across several models, including restarting an answer that an overload cut off midway.
• Structured output while streaming. A blocked or cut-off answer still arrives as partial JSON. We check why the answer stopped before parsing it, so the person gets a clear next step ("cover the ID numbers and try again", "upload fewer pages") instead of an error.
• Privacy in the details. In one test run, the model repeated a child's name from a filled-in form in its help text. We tightened the rule so filled-in values are never copied.
• 16 languages. Hand-translating the interface wasn't realistic, so Gemini translates the section headings along with the explanation. English error messages inside right-to-left pages also needed care so punctuation lands in the right place.

What we learned

Plain language takes more than translation. It needs structure: what to do first, by when, and what happens if you don't. Showing the source next to each point makes people far more willing to trust an AI explanation. And designing for failure (quotas, overloads, unreadable photos) matters as much as the happy path.

What's next

• Let people cover ID numbers on the photo before upload.
• Text-message reminders before each deadline.
• Shared explanations that a caseworker or family member can open.
• Partnerships with libraries, clinics, and community centers that already help people with paperwork.

Built With

• css
• next.js
• node.js
• react
• typescript
• vitest
• zod