ITR-1 Advisor Workspace

A local-first desktop workspace that helps Indian tax preparers screen, prepare, review, and track ITR-1 returns without sending client data to the cloud.

Comment

Inspiration

Filing an Income Tax Return sounds simple until a preparer is juggling multiple clients, Form 16s, AIS/TIS, 26AS, bank details, regime comparisons, confirmations, portal steps, and verification follow-up. I wanted to build a practical, privacy-first tool for a real everyday workflow: preparing Indian ITR-1 returns for AY 2026-27 while keeping taxpayer records local and encrypted.

The design goal was not to replace the Income Tax Department portal or pretend to be legal advice. The goal was to make the preparation stage calmer, more structured, and less error-prone.

What it does

ITR-1 Advisor Workspace is a local desktop-style app for one preparer managing multiple client returns. It provides:

  • A passphrase-encrypted local vault for client records and source documents.
  • A multi-client advisor dashboard with lifecycle states such as Draft, Review required, Ready to export, Exported, Submitted, Verification pending, and Verified.
  • An ITR-1 eligibility wizard for AY 2026-27 that blocks export when a client appears ineligible.
  • Side-by-side old-regime and new-regime tax estimates.
  • Structured entry for taxpayer details, income, house property, deductions, taxes paid, refund bank details, challans, and filing status.
  • Local PDF text extraction for Form 16, AIS/TIS, Form 26AS, and proof documents.
  • Reviewable extracted-field suggestions with page/source provenance and explicit confirmation before use.
  • Export blockers for missing confirmations, incomplete fields, eligibility failures, and validation issues.
  • A human-readable review PDF and a preparation JSON handoff for official-utility validation.
  • A manual filing and verification tracker for acknowledgement number, submission date, and verification outcome.
  • Encrypted backup/restore and a deliberate forgot-passphrase reset flow.

The app intentionally does not log in to the Income Tax portal, store portal credentials, or submit returns. Final validation and upload must happen through the official Income Tax portal, the current official offline utility, or an approved ERI workflow.

How we built it

The project is built with:

  • React and TypeScript for the desktop-style user interface.
  • Vite for local development and production builds.
  • Tauri/Rust scaffolding for native macOS and Windows packaging.
  • WebCrypto with PBKDF2-SHA-256 and AES-256-GCM for the encrypted local vault.
  • IndexedDB for encrypted document attachment storage.
  • PDF.js for local PDF text extraction.
  • jsPDF for review PDF generation.
  • Vitest for tax and eligibility test coverage.
  • Codex as the build partner for architecture, implementation, debugging, security tradeoffs, test creation, and submission documentation.

The app was built as a local-first system because taxpayer data is sensitive. The passphrase-derived key stays in memory only while the vault is unlocked, and exported files carry explicit warnings when they leave the encrypted vault.

Challenges we ran into

The hardest part was balancing usefulness with honesty. A tax app should not pretend to do more than it safely can. The official AY 2026-27 ITR-1 schema requires registered software identifiers and a digest, so the app does not forge a portal-submittable JSON. Instead, it produces a preparation handoff and review PDF, then guides the preparer to validate and generate the final upload file in the official utility or an approved ERI product.

Another challenge was keeping document extraction assistive rather than authoritative. The app can extract text from machine-readable PDFs, but every imported value must be reviewed and confirmed. Scanned documents are retained for manual review rather than silently guessing.

I also ran into practical desktop delivery issues: opening a Vite source index.html directly causes a blank page, so I fixed the production build paths, added a local launcher, and documented the correct run path.

Accomplishments that we're proud of

  • Built a complete end-to-end tax preparation workflow rather than just a calculator.
  • Added a real encrypted vault with encrypted attachments and backup/restore.
  • Made privacy a product feature, not a footnote.
  • Implemented ITR-1 eligibility checks, regime comparison, blockers, warnings, and verification tracking.
  • Added a review PDF and a plain-English user guide PDF.
  • Handled the lost-passphrase case honestly: no recovery theater, just a clear reset path.
  • Kept the app aligned with the boundary that final filing belongs to the official portal or utility.

What we learned

I learned how much of a tax-preparation workflow is not just calculation. A good tool needs provenance, review states, warnings, exports, backups, human confirmation, and a clean handoff to the official system.

I also learned that local-first security changes the product design. If a vault is genuinely encrypted, forgotten passphrases cannot be recovered. If source documents are sensitive, extraction should happen on-device. If an exported file leaves the vault, the app should say so clearly.

Codex helped me move quickly through the full loop: requirement shaping, official-rule research, implementation, tests, packaging, bug fixes, and documentation.

What's next for ITR-1 Advisor Workspace

Next steps would include:

  • Native packaged installers for macOS and Windows after completing Rust/Tauri packaging on a machine with the full toolchain.
  • A separately reviewed rule-pack update process for future assessment years.
  • Better OCR support with bundled local OCR models for scanned PDFs.
  • Stronger reconciliation screens for salary, interest, TDS, and challan mismatches.
  • More official-utility fixture validation.
  • Optional guided sample data for judges and demos.
  • Support for additional ITR forms only after separate legal/tax-rule review.

Built With

Share this project:

Updates