GreenPath

Inspiration

The U.S. green card process is one of the highest-stakes things many families ever go through, and yet most of the guidance around it is scattered across dozens of pages, buried in dense legal language, and easy to misread when you are already stressed. We watched people in our own communities try to navigate forms like the I-485 and I-130 with nothing but a stack of PDFs and a search engine, and we kept seeing the same pattern of avoidable mistakes, missed deadlines, and confusion about when a situation actually needs a lawyer. We wanted to build something that respects how serious this process is while making it far easier to understand, and we wanted it to be honest about its own limits from the very first screen.

What it does

GreenPath turns the green card process into a guided, plain-language journey while staying clear at every step that it provides general information and never legal advice. The Pathway Finder lets someone describe their situation in their own words and suggests their most likely category across family, employment, humanitarian, diversity, and investment routes, along with a confidence level and concrete next steps. Document Review accepts pasted form entries and flags the kinds of issues that commonly trigger a Request for Evidence before a person files, such as missing address history, sponsor income evidence, or vaccination records. Interview Prep runs a USCIS-style practice session where an AI officer asks one question at a time and coaches each answer. Stage Q&A gives plain-language answers tuned to a person's pathway and current stage in whatever language they ask in, and the Deadline Alerts feature reads a sentence describing a case and extracts biometrics, interview, and Request for Evidence dates into a visual timeline. Layered on top of all of this are language tools that translate, auto-detect language, scan documents through in-browser OCR and PDF parsing, and read results aloud, with an honest per-language capability matrix rather than a blanket claim of supporting every language equally.

How we built it

The canonical app is a single-file frontend in public/index.html, served by a Flask backend in server.py that also exposes the JSON API endpoints under /api. Each AI feature talks to OpenAI's gpt-4o-mini and gpt-4o models through a strict JSON contract so every response stays structured and predictable, and the in-browser document tools are built on tesseract.js for OCR and pdf.js for PDF handling, with the Web Speech API powering read-aloud. Behind the AI sits a grounding layer made of curated datasets, a visa-wait estimator computed from real Department of State Visa Bulletin history, and a retrieval module that pulls answers back to official sources. The most important architectural decision was putting a deterministic, server-side attorney-handoff check in handoff.py that runs before any model call on all five AI endpoints, so the system can refuse and route to real help without ever depending on the model to make that judgment.

Challenges we ran into

The hardest problems were the ones where being helpful and being safe pulled in different directions. Detecting high-risk situations such as removal proceedings, criminal history, fraud, asylum deadlines, and unauthorized work had to be reliable enough to catch genuinely dangerous cases while not firing on ordinary benign questions, and getting both the recall and the false-positive rate right took a lot of careful tuning and dedicated tests. Keeping the AI grounded was another constant battle, since the model naturally wants to sound confident and give advice, so we wrapped every endpoint in strict JSON contracts and a no-legal-advice framing that points back to official sources. We also had to be honest about language support, because OCR and read-aloud quality vary a great deal by device and language, which is why we built a tested language matrix that reports real per-language status instead of overpromising.

Accomplishments that we're proud of

We are proud that the safety stop is deterministic and tested rather than something we just hope the model gets right, and that it is reused consistently across every AI endpoint. The project ships with 281 passing tests and a deterministic evaluation that scores 72 out of 72, covering handoff precision and recall, the visa estimator, grounding and no-legal-advice framing, retrieval, and a dataset freshness gate, and because that evaluation calls no model, the number is identical on every single run. We added an offline demo mode so a live judging session never shows a broken AI feature, a freshness gate that fails the build when curated immigration data ages past its threshold, and a privacy posture that keeps document scanning in the browser and discloses clearly what gets sent to the server. Continuous integration runs the tests, the evaluation, and a secret-scanning job on every push.

What we learned

We learned that the most valuable thing an AI product in a high-stakes domain can do is know when to stop, and that earning trust comes from visible boundaries, honest labeling, and tests rather than from confident-sounding answers. Building the deterministic handoff taught us how to separate the parts of a system that must never depend on a model from the parts where a model genuinely helps, and working through the freshness gate showed us how quickly immigration data goes stale and why surfacing that staleness honestly matters more than pretending the information is always current. We also came away with a much deeper respect for how language access shapes who can actually use a tool like this.

What's next for GreenPath

We want to broaden the grounded dataset coverage and keep the Visa Bulletin estimates current as new bulletins publish each month, and we want to expand the tested language matrix so more people can rely on OCR, read-aloud, and handoff detection in their own language. We also plan to deepen the location-aware attorney-handoff resources so that when GreenPath stops and routes someone to real help, the legal aid and official-source links are as specific and useful as possible. The longer-term goal stays the same as it was on day one, which is to make green card preparation more understandable, more accessible, and safer than asking an unrestricted chatbot.

Built With

• anthropic
• claude
• codex
• css
• flask
• gpt-4o
• html
• javascript
• openai
• pdf.js
• playwright
• pytest
• python
• tesseract.js
• vite
• web-speech-api