TaxMate

1.1M int'l students overpay US taxes yearly. TaxMate is free AI that helps F-1/J-1 students file, find treaty benefits & recover illegal FICA withholdings.

Comment

TaxMate 🎓💙

Free AI Tax Assistant for F-1 & J-1 International Students

A student who traveled across the world to study here deserves the same access to tax help as everyone else — for free.

💡 Inspiration

Every April, over 1.1 million international students on F-1 and J-1 visas face the same nightmare: a US tax system that was never designed for them. The forms are confusing, the terminology is impenetrable, and the stakes are real — file wrong and you risk visa complications.

Most students either pay hundreds of dollars to a CPA, rely on outdated PDFs from their university, or just guess.

TaxMate was born to fix that.

🤖 What It Does

TaxMate is a free AI-powered tax assistant built specifically for F-1 and J-1 international students. You chat with Maya — a friendly AI — who guides you through the entire filing process in plain English, step by step.

Feature Details
🌍 Treaty Detection Auto-detects your tax treaty by home country. Students from China, India, South Korea, Germany, and 15+ other countries qualify for exemptions worth up to $2,400/year
⚠️ FICA Recovery F-1/J-1 students are legally exempt from Social Security & Medicare taxes, but employers frequently withhold them anyway. Maya catches this instantly
📄 Document Reading Upload a photo of your W-2 or Form 1042-S — Claude Vision extracts all data automatically
📋 Form Generation Generates Form 8843, Form 1040-NR, and Form 8833 filled with your real data, ready to sign and mail
📦 Download Package Everything bundled into a single ZIP with personalized filing instructions

🛠️ How We Built It

Layer Technology
Frontend React + Vite + Tailwind CSS — split-screen layout with Maya's avatar on the left, guided chat on the right
Backend Node.js + Express — conversation state, document processing, PDF generation, ZIP packaging
AI Brain Anthropic Claude API (claude-sonnet-4-6) — full conversation flow, structured data extraction, and Claude Vision for W-2/1042-S reading
PDF Generation pdf-lib — programmatically fills IRS Forms 8843, 1040-NR, and 8833
Tax Logic Custom treaty detection engine (15+ countries) + automatic FICA exemption checker
Privacy multer with memory-only storage — uploaded documents are never written to disk

🧱 Challenges We Ran Into

Keeping Claude on track — The conversation needed to extract structured tax data while still feeling warm and natural. We spent significant time tuning the system prompt to balance data extraction with personality, and to prevent Claude from re-requesting documents the user had already uploaded.

IRS form field mapping — PDF form fields have cryptic internal names like topmostSubform[0].Page1[0].f1_1[0]. Getting the data to land in the right boxes took careful mapping.

HeyGen API sunset — We initially integrated HeyGen's Streaming Avatar SDK for a live video avatar, but discovered mid-build that their entire streaming API was sunset in March 2026. We pivoted to a polished animated fallback avatar so the experience remained seamless.

State synchronization — After a document upload, the updated tax data needed to reach Claude before it responded, but React's async state updates meant Claude was seeing stale data and kept re-requesting uploads. We solved this by passing the fresh data object directly to the API call instead of relying on state.

🏆 Accomplishments We're Proud Of

  • ✅ End-to-end FICA detection — upload a W-2 photo → Claude Vision reads it → FICA check runs → student sees exactly how much was wrongly taken and how to recover it, all within seconds
  • ✅ Article-level treaty specificity — not just "a treaty exists" but "Article 20 of the US-China treaty exempts your income for 5 years"
  • ✅ Complete downloadable tax package — real IRS-structured PDFs + personalized instructions, all in one ZIP
  • ✅ Zero data persistence — no user data is ever stored, logged, or persisted beyond the browser session

📚 What We Learned

  • Claude's structured output pattern — embedding JSON in <data> tags alongside conversational text — is a powerful technique for AI workflows that need to both talk to users and drive application logic simultaneously
  • Tax law for international students is genuinely complex and underserved — the gap between what students need and what's available is enormous
  • UX clarity matters as much as AI quality — the friendliness and pacing of Maya's responses had as much impact on the experience as the correctness of the tax logic

🚀 What's Next for TaxMate

  • [ ] State tax support — California 540NR, New York IT-203, and other nonresident state forms
  • [ ] ITIN application guidance — walk students through Form W-7 if they don't have an SSN yet
  • [ ] Multi-year support — help students amend prior years when they discover a missed treaty benefit
  • [ ] University partnerships — integrate directly with international student offices
  • [ ] Expanded treaty database — currently 15 countries, target is full IRS coverage (70+ countries)
  • [ ] E-filing pathway — nonresident aliens currently can't e-file, but we'll be ready when that changes

Built With

Share this project:

Updates