Add IRS refund tracker WebHarbor mirror

[Lxr-max]

Site

• Site name: IRS Refund Tracker
• Site slug: irs_refund
• Upstream URLs:
  • https://www.irs.gov/refunds
  • https://sa.www4.irs.gov/wmr/
• Contribution type: New Website
• Contributor: XuanRui LI / Lxr-max
• Contact email: mingduanmu845@gmail.com

Safety / Privacy Note

This mirror uses synthetic demo taxpayer data only. It does not use real SSNs, real taxpayer identities, or live IRS lookup services.

Implementation Summary

This PR adds a local IRS refund tracker mirror with a government-style lookup flow, result timeline, notices, FAQ/help content, account pages, lookup history, and deterministic synthetic refund records. The implementation is built with Flask, SQLAlchemy, Jinja2, and SQLite, with no external runtime calls.

Key User Flows

• Start and complete a refund lookup using synthetic last-four demo fields
• View result pages for approved, sent, processing, delayed, and mismatch scenarios
• Browse help articles, FAQ entries, notices, and tax topics
• Log in, edit account preferences, and inspect saved lookup history

Seed Row Counts

• users: 4
• taxpayer_profiles: 60
• tax_returns: 100
• refund_statuses: 100
• refund_timeline_events: 237
• help_articles: 30
• faqs: 25
• notices: 20
• filing_statuses: 5
• lookup_histories: 12
• document_checklist_items: 12
• alerts: 4

Benchmark Users

• alice.j@test.com
• bob.c@test.com
• carol.d@test.com
• david.k@test.com
• Password: TestPass123!

Tasks

• Task count: 18
• Task categories: refund lookup, delayed reason identification, help/article search, FAQ usage, notice-code explanation, account editing, saved history, tax-year comparison, delivery method lookup, mismatch diagnosis, checklist lookup, multi-page reasoning

WebSyn Port

• Selected port: 40015

Verification Summary

• Docker build and container run completed successfully
• Key routes including home, refunds, where-is-my-refund, refund-status start flow, help, FAQ, search, notices, and login returned 200
• Register/login/logout, search, refund lookup success, mismatch and delayed cases, account edit, lookup history, help article navigation, and notice pages were smoke-tested successfully
• Reset endpoint POST /reset/irs_refund returned ready successfully
• instance/irs_refund.db and instance_seed/irs_refund.db matched after reset
• MD5: bcd6d6080a0cad3a5d8e88803e92ffaa

Screenshot Paths

• Local review screenshots: C:\Users\34475\Desktop\VScode\WebHarborRepo\sites\irs_refund\scraped_data\submission_review

HF Asset Status

HF asset PR is open and pending merge: https://huggingface.co/datasets/ChilleD/WebHarbor/discussions/27

This GitHub PR is opened for code review first. The local instance_seed DB and static assets were prepared locally and uploaded through the HF asset workflow.

Known Limitations

• Uses synthetic demo taxpayer data only
• No live IRS calls and no real taxpayer information
• Final .assets-revision update still depends on HF asset PR merge

Manual Review Notes

• Please review the government-style visual rhythm and result timeline clarity
• Please confirm all user-facing copy makes the synthetic/demo nature explicit
• Please spot-check lookup tasks for stability and lack of answer leakage

[Susan571]

Review — Add IRS refund tracker WebHarbor mirror (#37)

Verdict: Request changes (one blocker), then Approve. Code correct; full runtime suite
passes once assets exist.

Mechanical

• Registration synced in all 3 places. py_compile OK.
• ❌ Blocker: build.sh → check_assets.sh fails:
  MISSING (required): sites/irs_refund/instance_seed. No irs_refund.tar.gz on HF and
  .assets-revision not bumped. Generate instance_seed/irs_refund.db, upload tarball,
  bump revision.
• ✅ After generating the seed and building: 16/16 sites → 200, /reset/irs_refund
  byte-identical (md5 match), /reset-all ~1.3s. Self-seed is idempotent
  (100 refund_statuses / 100 tax_returns / 60 profiles / 237 timeline events).

Visual fidelity: PASS

Clean IRS-style form/status UI (screenshots: irs_home.png, irs_lookup.png); placeholders
acceptable for a form site.

Functional depth: PASS

Drove /refund-status/start → verify → result end-to-end: demo case Nora Patel
(WMR-2024-8443) → "Delayed: Offset Review / Paper check". Seeded accounts, notices, FAQ, and
search all work.

Task quality: 18/18 PASS

All named demo cases and benchmark accounts verified present. Multi-step lookups,
seeded-account drill-downs, profile edits, plus a nice negative case (Task-10: wrong ZIP
00000 → which field is incorrect). Port :40015 correct.

Nit (non-blocking): the verify step auto-prefills the correct ZIP/last-4, lowering
friction on the identity step; consider leaving it blank so verification is a real step.

Required before approval: upload the IRS asset tarball to HF + bump .assets-revision.