Build a secure, auditable, role-based web application called “ITR Tracker” for an Indian CA firm to manage and monitor the entire lifecycle of Income-tax Return (ITR) filings per client and assessment year (AY): from data request → data receipt → KYC/consent capture → document vetting → tax computation & review → e-filing → e-verification → CPC processing/refund → closure. The system must maintain a tamper-evident activity log (who did what, when, where, and before/after snapshots), surface SLA breaches, and generate MIS dashboards. Ship a working app on Replit with seed data, docs, and tests.

Non-negotiables: strong RBAC, immutable audit log, structured workflows, CSV/Excel import/export, attachments, comments & mentions, reminders (email/WhatsApp placeholder hooks), end-to-end tests, Swagger docs, and Replit deploy scripts.

Compliance & Governance (India, high level)

Design for:

Income-tax Act, 1961 & Rules, 1962 (records retention; correctness of filings; audit trails for review).

IT Act, 2000 (Sec. 65B electronic records) – ensure evidentiary quality of electronic logs/exports.

DPDP Act, 2023 (privacy-by-design principles) – data minimization, purpose limitation, consent capture, access controls, and deletion requests workflow.

Professional confidentiality (ICAI Code of Ethics) – least-privilege access, encrypted storage at rest (where feasible on Replit), redaction utilities for PAN/Aadhaar in UI lists.

Include: consent capture, data-sharing logs, and a Policy & Audit page listing retention defaults (e.g., 8 years), export of activity log to PDF/CSV for compliance reviews, and IP/timestamp recording on critical actions.

Tech Stack & Project Setup (Opinionated)

Backend: Python FastAPI, SQLAlchemy, Pydantic, Uvicorn, Alembic migrations.

DB: SQLite for Replit (dev), ready for Postgres env var in production.

Frontend: React (Vite), TypeScript, TailwindCSS, shadcn/ui for components, React Query.

Auth & RBAC: JWT (access+refresh), password hashing (argon2/bcrypt), roles & granular permissions.

File Storage: Local /uploads on Replit; abstraction layer to swap to S3/GDrive later.

Docs & Tooling: OpenAPI/Swagger, Postman collection, pre-commit (black, isort, ruff), pytest + coverage, GitHub-style Actions (locally simulated), Makefile/NPM scripts.

Charts: Chart.js for dashboards.

Messaging Hooks: SMTP (email), WATI/Twilio webhooks placeholder for WhatsApp (config via ENV).

Security: CORS hardening, rate limiting, input validation, server-side file type & size checks, signed download URLs, basic WAF patterns.

Deliverables: monorepo with backend/ and frontend/, .replit & replit.nix (or Poetry) configured to run both services via a simple make dev.

Core Roles (RBAC)

Partner/Admin – full control, policy settings, SLA templates, view everything.

Manager/Reviewer – assign staff, approve/reject stages, review computations.

Staff/Article – execute tasks, upload docs, update checklists, raise flags.

Client (optional portal) – upload documents, view status, approve deliverables, sign consent.

Auditor (read-only, time-boxed) – view logs & evidence packs.

Include a permissions matrix (CRUD per entity + “transition” rights) and enforce at API & UI route level.

Entities & Data Model (SQLAlchemy)

Implement these tables with indices, soft-delete flags (where needed), created_at/updated_at, and system clock + user time zone capture:

users (id, name, email, mobile, role, is_active, last_login_at, 2FA_secret_opt)

clients (id, display_name, legal_name, PAN, Aadhaar_last4, DOB/incorporation_date, address, contacts[], risk_category, tags[])

engagements (id, client_id, AY, itr_form_type [ITR-1…ITR-7], status, tier [Individual/HUF/Firm/Company/Trust], is_audit_applicable [44AB, 44ADA, 44AE], due_dates[], sla_profile_id, priority)

assignments (id, engagement_id, user_id, role_on_case [Preparer/Reviewer/Partner], start/end)

documents (id, engagement_id, doc_type [26AS/AIS/TIS/Form16/BankStmt/CapitalGains/LoanInt/Donation/HP/Business/3CB-3CD JSON etc.], file_name, path, checksum, size, uploaded_by, uploaded_at, client_visible bool, version)

checklists (id, engagement_id, name, version, is_template bool)

checklist_items (id, checklist_id, item, section_ref [e.g., “Sch CG – 112A”], mandatory bool, status [Pending/In-Progress/Done/NA], assignee_id, due_at, completed_at, notes)

computations (id, engagement_id, engine [excel/python], version, summary_json [income heads, deductions, tax, surcharge, cess], attachments[], prepared_by, reviewed_by, review_status, remarks)

efiling (id, engagement_id, json_uploaded bool, ack_no, filed_at, e_verify_status [Pending/DONE/By Aadhaar OTP/Bank/DSC], e_verified_at, cpc_status [Processed/Defective/Notice], refund_status [Issued/Pending/Adjusted], refund_amount, cpc_comm_ref)

comments (id, engagement_id, entity_type, entity_id, author_id, body, mentions[], created_at)

reminders (id, engagement_id, channel [Email/WhatsApp/SMS], template_key, schedule_at, sent_at, status, payload_json)

sla_profiles (id, name, stage_targets_json {stage→hours}), sla_events (id, engagement_id, stage, breached bool, breached_at)

activity_log (id, actor_user_id, actor_role, action, entity_type, entity_id, ip, user_agent, ts, before_json, after_json, signature_hash) → append-only, immutable

status_transitions (id, engagement_id, from_status, to_status, reason, actor_user_id, ts)

tags (id, name), entity_tags (id, entity_type, entity_id, tag_id)

Create migrations; seed with demo roles/users/clients/engagements.

Lifecycle & Status Machine (enforceable)

Define strict, named statuses (enum) for engagements.status, transitions recorded in status_transitions and activity_log:

Data Requested

Data Received – Preliminary

KYC/Consent Captured

Doc Indexing & Vetting

26AS/AIS/TIS Imported & Reconciled

Computation Prepared

Manager Review

Partner Review

Client Review & Sign-off

ITR Created & JSON Validated

ITR Filed – Ack Captured

E-Verification Pending

E-Verification Done

CPC Processing

Refund/Adjustment Update

Closed

Each stage has SLA targets (hours) from sla_profiles. On status change, trigger SLA evaluation and optional reminders.

Checklists (by ITR form & profile)

Ship templates that auto-expand into per-engagement checklists:

Individuals/HUF: Personal particulars, PAN/Aadhaar link check, 26AS/AIS/TIS download, Form 16, Interest, Rent & HP, Capital Gains (brokerage summary), Deductions (80C/80D/80G etc.), Advance/SA tax challans, Exempt income, Foreign income/FA schedule if applicable.

Firms/LLP/Companies/Trusts: Audited/unaudited status, 3CB-3CD or 3CA-3CD readiness, depreciation blocks, turnover/gross receipts, presumptive vs regular, TDS/TCS reconciliations, ledgers & bank statements, related party disclosures.

Edge cases: Loss carry-forward continuity, MAT/AMT, 112A/111A split, ESOP perquisite, HRA proof hygiene, 80G receipts validation, donation lookup, housing loan certificate, rent agreement.

Key Features (MVP+)

Client & Engagement Management: AY-wise, ITR type, tags, priority.

Document intake & versioning: Drag-drop uploader with type validation; checksum dedupe; version history.

CSV/Excel import/export: Clients, engagements, checklist items, and bulk status updates. Provide downloadable CSV templates.

Computation record: Attach summary JSON + files (Excel/PDF).

Reviews: Two-level review (Manager → Partner) with change requests.

E-filing capture: Ack no., filed_at, e-verification mode & time, CPC/Refund tracking.

Comments & @mentions with email/WhatsApp placeholders.

Dashboards & KPIs:

Pipeline by stage, aging buckets, SLA breaches.

Per-staff workload & productivity (items closed, TAT).

Due-date heatmap by AY & ITR type.

Risk flags (missing AIS vs 26AS mismatches, open review notes).

Search & Filters: client, PAN, AY, status, assignee, tags, overdue.

Immutable Activity Log: append-only, signed hashes, exportable CSV/PDF.

Access Controls: field-level masking (PAN partial), client-portal limited scope.

Policy Center: retention settings, download request log, privacy notice, consent records.

Settings: SLA profiles, reminder templates, ITR form checklists, tag manager, email/WhatsApp SMTP/API configs.

API Surface (illustrative)

Build REST endpoints with validation & RBAC guards; include OpenAPI:

/auth/register, /auth/login, /auth/refresh, /auth/me

/users, /roles, /permissions

/clients (CRUD, bulk import/export)

/engagements (CRUD, status transition POST /engagements/{id}/transition)

/assignments (CRUD)

/documents (upload/download; server-side MIME validation; signed URLs)

/checklists & /checklist-items (CRUD, template expand)

/computations (CRUD)

/efiling (CRUD)

/comments (CRUD, mentions)

/reminders (schedule, send stub)

/dashboard/* (aggregate KPIs)

/activity-log (query/export; no delete/update routes)

/admin/policies (read/update)

/exports/* (CSV/Excel exports)

Frontend (React + Tailwind + shadcn/ui)

Pages & UX:

Login/2FA (optional)

Dashboard: pipeline funnel, SLA breaches, ageing table, staff leaderboard, calendar of due dates.

Clients: table with search; client detail with engagements tab.

Engagement detail: status ribbon, checklist panel (inline edits), documents pane with version history, computation card, e-filing card, comments with mentions, activity log tab, SLA indicators, quick actions.

Reviews: manager & partner boards (approve/reject with comments).

Reports: exportable tables and charts.

Settings: roles, SLA templates, reminder templates, checklist templates, message channel configs.

Policy & Audit: privacy, retention, consent summaries; activity log export.

UI rules: mask PAN on lists (ABCDE1234F → AB***1234F), reveal on detail with permission; highlight overdue in red; “stage chips” with clear color coding.

Activity Log & Evidence Pack (Critical)

Every change writes to activity_log with: actor, role, ip, ua, ts, action, entity_type/id, before_json/after_json diffs, and a signature_hash (HMAC using server secret).

Provide an Evidence Pack export per engagement: zip of final computation, ack, e-verification proof, checklist completion status, and CSV/PDF of activity log + status transitions.

No update/delete API on activity_log. Add admin report for verification of log integrity (recompute HMACs).

Reminders & Notifications

Template keys: DATA_REQUEST, REVIEW_DUE, SIGNOFF_REQUEST, E_VERIFY_PENDING, SLA_BREACH, CPC_UPDATE.

Channels: email (SMTP), WhatsApp (WATI/Twilio placeholders).

Implement a scheduler stub (APScheduler) for timed sends; in Replit, run in-process.

Seed Data

Create demo: 10 clients, 20 engagements across AY 2023-24/2024-25, mix of ITR-1/2/3/4, some audit-applicable, 100+ checklist items, sample documents (dummy files), 26AS/AIS flags, and a spread of statuses for dashboards.

Security & Quality

Input sanitation, size limits, allowed file types (PDF, XLSX, CSV, JPG-PNG).

Rate-limit auth & uploads.

Centralized exception handling with redacted error payloads.

pytest coverage > 80% on services, RBAC gates, status transitions, and log immutability.

OpenAPI served at /docs with auth.

DevEx & Replit

.replit runs make dev (backend on 8000, frontend on 5173, proxy via vite).

Makefile targets: dev, format, lint, test, seed, migrate, build, start.

ENV: JWT_SECRET, DB_URL, SMTP_*, WHATSAPP_API_KEY, SERVER_URL, FILE_STORAGE_DIR=/uploads.

Provide README.md with setup, ENV examples, and admin bootstrap command.

What to Generate Now (Artifacts)

Monorepo with backend/ (FastAPI), frontend/ (Vite React TS).

Alembic migrations for all tables.

Seed script to populate demo data.

OpenAPI schema + Postman collection.

Unit & API tests (pytest) incl. status machine & log immutability.

Frontend pages/components listed above, wired to API.

CSV templates for import/export (clients, engagements, checklist items).

Sample reminder templates (Jinja2) with variable substitution (client name, AY, due date).

Evidence Pack exporter (ZIP) per engagement.

README and Makefile to run on Replit out-of-the-box.

Acceptance Criteria (DoD)

Login, RBAC, and session refresh work.

Create client → create engagement → auto-expand checklist by ITR type → upload documents → update items → submit for Manager → Partner → Client sign-off → file ITR (ack captured) → e-verify → mark processed/refund.

Every step emits activity log entries with HMAC signature; log is queryable and exportable.

Dashboards show real data; SLA breaches & aging visible.

CSV import/export round-trips without data loss.

Files stored with checksum/versioning; downloads audited.

Lints/tests pass; OpenAPI accurate; Replit “Run” boots both tiers.

Stretch (Phase-2, keep code extensible)

Client self-service portal (limited scope).

AIS/26AS parsers (manual upload → auto-reconcile deltas & flags).

Notice/workflow module (143(1), 139(9), 142(1) etc.) with timelines.

E-mail to thread ingest (save to comments/documents automatically).

S3/GDrive storage backend.

Multi-tenant (firm-level orgs), billing & invoicing, TDS/GST cross-linking.

Build now. Create the repo, scaffold backend & frontend, implement the models, endpoints, UI, tests, seed data, and Replit run configuration exactly as specified above. Ensure production-grade structure, defensive coding, and clear documentation throughout.

Notes for the Agent

Be explicit and opinionated; don’t leave TODOs.

Include sample .env.example.

Where live integrations aren’t possible on Replit, implement stubs/interfaces with clear extension points.

Prefer typed Python & TS; keep functions small and testable.

Optimize for maintainability and auditability over “quick hacks”.

(Optional) Quick Message Templates (pre-filled)

Data Request (Client): “Dear {{client_name}}, please upload AY {{ay}} documents via your secure portal link {{link}} by {{due_date}}. Regards, {{firm_name}}.”

Review Due (Manager): “Engagement {{client_name}}-{{ay}} awaits Manager review since {{date}}; SLA breaches in {{hours_remaining}}h.”

E-Verify Reminder: “ITR for {{client_name}}-{{ay}} filed {{filed_at}}; e-verification pending. Use Aadhaar/Bank/DSC within 120 hours.”