TurtleTax

File your taxes without the stress.Upload your tax documents and we'll walk you through every line — with plain-English explanations at each step.

Comment

Inspiration

Tax season is already stressful. For international students on F-1 and J-1 visas, it's a minefield — nonresident alien status, Form 8843, treaty exemptions, the Substantial Presence Test. The go-to solution, Sprintax,
charges $51 for federal and another $40 for Maryland state returns. That's $91 out of pocket for a grad student earning campus wages. We thought: this is a solvable problem. We had 48 hours, a Claude API key, and a lot of caffeine.

What it does

TurtleTax is a free, AI-powered tax filing assistant built for UMD students — both US residents and international F-1/J-1 visa holders.

Upload your W-2, 1042-S, or 1098-T and TurtleTax:

  1. Determines your filing status by walking you through a short residency questionnaire (including the Substantial Presence Test for international students)
  2. Extracts your tax data from uploaded documents using Claude's vision capabilities
  3. Pre-fills your federal and state returns — Form 1040 or 1040-NR, Maryland Form 502 or 505, and Form 8843 for international students
  4. Explains every line in plain English — click the ⓘ next to any line and Claude pulls the exact explanation from the IRS instructions, with page citations
  5. Downloads your filled returns as a ready-to-mail PDF zip — with mailing addresses and next steps included

No account. No subscription. Documents never stored.

How we built it

  • Frontend: Next.js 15 with TypeScript, styled entirely with inline CSS (no Tailwind, no component library — full control). UMD branding throughout with a custom design system using CSS variables for colors, typography (Playfair Display + DM Sans), and animations.
  • State management: Zustand store that threads document data, residency answers, and computed tax values across the whole flow.
  • AI extraction: Claude processes uploaded PDFs and images to extract structured data (wages, withholding, treaty amounts) via a /api/extract endpoint, validated with Zod schemas for W-2, 1042-S, and 1098-T.
  • Tax computation: A /api/compute route applies the actual 2025 tax rules — standard deduction, Maryland's 15% deduction floor, Prince George's County local tax rate, and nonresident exemptions.
  • PDF generation: A /api/fill-pdf endpoint generates filled, print-ready tax forms bundled into a downloadable zip.
  • Explain panel: Claude provides line-by-line explanations with IRS instruction citations, surfaced inline as a slide-out panel on the forms page.

Challenges we ran into

The hardest part wasn't the AI — it was the tax law. The federal and Maryland nonresident tax rules interact in subtle ways: treaty amounts reduce 1040-NR income but flow differently to Maryland Form 505; the Substantial Presence Test has exceptions for F-1 and J-1 visa holders that override the day-count math; Maryland's local tax depends on county of residence, not just state. Getting those calculations right required reading actual IRS and Maryland Comptroller instructions, not just approximating.

On the engineering side, keeping document data flowing cleanly from upload → extraction → computation → form prefill without unnecessary re-renders or stale state across four pages required careful Zustand store design. PDF generation in a serverless Next.js environment also had constraints we hadn't anticipated.

Accomplishments that we're proud of

  • Built a full end-to-end tax filing workflow — from "what's your visa type?" to a downloadable, mail-ready return — in 48 hours.
  • The Substantial Presence Test wizard correctly handles F-1 and J-1 exempt year rules, something Sprintax charges $91 to do.
  • The inline "Claude explains" panel with IRS citation is genuinely useful — it's the feature we wish existed when we filed our own taxes.
  • The design doesn't look like a hackathon project. Every interaction has transitions, every state is handled, and the UMD identity is woven in without being gimmicky.

What we learned

Tax software is deceptively complex. Every edge case — a scholarship that's partially taxable, a treaty that exempts wages but not fellowship income, a student who switched visa status mid-year — is a branch in the decision tree that breaks naive implementations. We learned to trust primary sources (IRS publications, Maryland Comptroller instructions) over any cached knowledge.

We also learned how much Claude's document understanding accelerates the kind of structured-data-extraction work that would otherwise require custom OCR pipelines. Uploading a W-2 PDF and getting back a clean { wages: 18400, federalWithheld: 1227 } in one API call was one of those "this is the future" moments.

What's next for TurtleTax

  • E-filing integration: Partner with IRS Free File or a VITA site to enable direct e-filing instead of mailed returns.
  • More forms: 1099-DIV and 1099-B for students with investment income; Schedule C for those with freelance income.
  • Multi-university rollout: The residency rules and forms are the same everywhere — only the branding changes. We want to open-source the core and let student orgs at other universities deploy their own instance.
  • Treaty database: A searchable index of US tax treaty exemptions by country of citizenship, surfaced inline when a 1042-S is uploaded.
  • Prior year support: Amending a return is often where students get lost. TurtleTax could walk through that too.

Built With

Share this project:

Updates