A public-sector revenue authority (name withheld under NDA)
TaxLink Revenue Portal — an internal delivery codename, not a commercial product name.
The problem
Tax filing traffic is not merely seasonal, it is a spike: a very large share of annual submissions arrive in the final days before a deadline. A system sized for average load is a system that fails on precisely the days it matters.
Assessment was manual and inconsistent between officers, which produced disputes that consumed more staff time than the assessments themselves.
Constraints we had to design within
- Extreme, predictable load concentration around filing deadlines.
- Legal requirements on e-signature validity and record retention.
- Integration with FBR APIs on their availability and contract.
- A filer population spanning individuals and large corporate finance teams.
Approach
Size for the spike, not the average
Submission handling was decoupled from assessment processing so that accepting a filing — the part with the deadline attached — stays fast under load, while assessment runs behind it. Capacity planning was done against deadline-day traffic rather than annual averages.
Rule-based assessment with reasons attached
Automated assessment uses explicit rules that record why each determination was made. A filer disputing an assessment can be shown the reasoning, which resolves a large share of disputes before they become cases.
E-signature with a retention model
Signature validity has a legal retention requirement attached, so the signing workflow was designed together with the retention model rather than treating storage as an afterthought.
Engineering notes
Calculation logic versioned against effective dates
Revenue rules change, and they change with effect from a date rather than from deployment. A system that applies current logic to a historical filing produces a wrong answer confidently, which is worse than failing.
Calculation rules are versioned and selected by the effective date of the filing rather than by what is current, so a reassessment of a prior period reproduces the position that actually applied at the time.
Designing for citizens who file once a year
A tax portal has no regular users. Almost everyone arrives unfamiliar, under deadline, and often anxious — the opposite of a daily-use enterprise tool where learned behaviour carries the interface.
That argues for explicitness over efficiency: no hidden state, no assumed prior knowledge, and validation that explains what is wrong in the filer's terms rather than reporting a field-level error. Saving partial progress is essential rather than a nicety, because sessions are interrupted.
Peak load is the design point, not the average
Filing traffic is extremely non-uniform: a large share of annual volume arrives in the final days before a statutory deadline. Capacity planned from averages fails precisely when failure is most visible and least excusable.
Because the deadline is statutory, an outage is not lost revenue but a citizen unable to meet a legal obligation. The asymmetry justifies provisioning that looks wasteful for most of the year.
Outcome
Filing acceptance remains responsive during deadline peaks because it no longer shares a critical path with assessment.
Assessment determinations carry recorded reasoning, which reduces the dispute volume that reaches staff.
Figures above are drawn from delivery records held under NDA and are pending independent confirmation. Where a figure cannot be evidenced it will be removed rather than qualified.