The Balance Behind Every Screen: Thirteen Modules of Leave Screens Are One Arithmetic Identity

Mostafa Dhouib·10 min read

The Balance Behind Every Screen: Thirteen Modules of Leave Screens Are One Arithmetic Identity

The short answer. A leave and entitlement system normally arrives specified as a catalogue of screens. One brief described thirteen modules. Underneath all of them there is a single arithmetic identity: allocated, less used, less pending, equals available. Every screen is either a view of that number or a way of changing it. The identity is easy to get right on the happy path and hard to keep right through a cancellation after the calendar has changed, a double submission, a retrospective administrative adjustment, and a year-end reset. A click-through acceptance checklist exercises none of those four. The deliverable is the balance, not the screens, and acceptance has to be written against the balance.

A request arrived as a module list. Employee self-service, manager approval, delegation, calendar administration, holiday configuration, accrual setup, reporting, notifications, audit, roles, imports, integrations, year-end. Thirteen of them, each with its own screens, each with its own acceptance line in the plan.

Read it as a module list and you plan a build measured in screens delivered. Read it as a balance and you plan a different build, because the thirteen modules are mostly presentation and the risk is concentrated in one number that almost nobody in the brief mentioned.

Thirteen modules, one number

Write the identity down first, because once it is written the shape of the system stops being negotiable.

Available equals allocated, less used, less pending.

Allocated is what the person is entitled to for the period, which may come from a policy, a contract, an accrual rule, a carry-over calculation, or a manual grant. Used is what has been taken and is final. Pending is what has been requested and not yet resolved, which is deducted because an employee must not be able to commit the same day twice while an approval sits in a queue.

Now go back through the thirteen modules. Self-service reads the identity and proposes a change to pending. Manager approval moves an amount from pending to used, or releases it. Calendar administration changes the meaning of a day and therefore the arithmetic of requests already recorded against it. Accrual setup changes how allocated is computed. Year-end changes allocated for the next period as a function of the previous one. Reporting reads the identity across people and dates. Notifications report that the identity changed.

That is not thirteen problems. It is one invariant with thirteen interfaces, and the interfaces are the cheap part.

The four places the identity breaks

The happy path is trivial. Request three days, approve three days, balance goes down by three. Every one of these systems gets that right in the first week, which is precisely why the first week of demos tells you nothing.

Cancellation after a calendar change. An employee requests five consecutive days. Later an administrator declares one of those days a public holiday, or moves a holiday, or changes the working pattern on that person's contract. Then the employee cancels. How many days come back? The number taken, or the number that would be taken if the request were made today? The two have diverged, and the difference stays in the balance permanently. Most implementations recompute from the current calendar on cancel, which silently credits or debits the employee for an administrative action they never saw.

Double submission. A manager taps approve, the response is slow, they tap again. Or a mobile client retries a request it believes failed. Two transitions, one intent. Without a notion of which request is being approved and whether it has already moved, pending is decremented twice and used is incremented twice, and the balance is wrong by exactly the amount of the request.

Administrative adjustment. Somebody in payroll says this person should have two more days because of a decision taken outside the system. If the adjustment is applied by editing the balance, the balance now holds a value nobody can derive and nobody can explain. If it is applied retrospectively, dated before transactions that already happened, then every figure printed since that date was wrong and nothing in the system says so.

Year-end reset. Carry-over caps, expiry dates, lapse rules, pro-rating for people who joined or left mid-period. The usual implementation writes a new allocated figure and overwrites the old period. After that the previous year cannot be reconstructed, which means a correction to the previous year cannot be made at all.

Each of these is arithmetic on a shared quantity under concurrency and time. None of them is a screen.

A click-through checklist cannot see any of this

Acceptance for this class of system is usually a list of user journeys. Log in as an employee, submit a request, see it in the list. Log in as a manager, approve it, see the balance decrease. Tick, tick, tick.

Every one of those passes on a system with all four defects above. The checklist walks the happy path by construction, because a journey is a happy path with a name. It has no step for changing the calendar underneath a request that already exists. It has no step for submitting the same approval twice inside the same second. It has no step for reconstructing what a balance was at the end of the previous financial year.

This is the practical reason these projects go wrong late rather than early. The build passes acceptance, goes live, and then the balances start being questioned. By the time somebody asks how an employee ended up with a fractional day they cannot account for, the system has no mechanism to answer, and that answer is the thing the customer actually bought.

Write acceptance against the balance

The fix is not more testing. It is moving acceptance from the interfaces to the invariant.

State the identity in the contract. One line, agreed by the people who will later dispute a figure. If allocated, used and pending are not defined to the point where two people compute the same available number from the same facts, the project has no specification regardless of how many screens are described.

Make the four stress cases acceptance criteria. Not test cases, acceptance criteria, with expected outcomes written down in advance. What comes back on cancellation after a calendar change is a policy decision, and it has to be made by the customer rather than discovered in the code.

Require explainability at a date. The system must be able to say what a balance was on any past date and why. That single requirement forces the architecture, because a balance stored as a mutable column cannot satisfy it and a balance derived from recorded entries can.

Require a concurrency test, not a concurrency review. Two simultaneous approvals of the same request, run as an automated test, with the balance asserted afterwards. A review will conclude that it is fine. The test will tell you whether it is.

Count adjustments as first-class operations. An administrative change with a reason, an author and an effective date is a feature. An edit to a number is a defect with a user interface.

The reframing is unwelcome before it is useful

Saying the deliverable is the balance rather than the screens is an unpopular thing to say in a procurement conversation. The module list is what was approved. It is countable, it maps to a schedule, and it lets everyone see progress. A single arithmetic identity is none of those things.

So the reframing has to be additive. The thirteen modules still get built. What changes is where the engineering care goes, which stress cases go into acceptance, and what the system is required to be able to explain. In practice this shifts a modest amount of effort from screen polish to the balance layer, and a much larger amount of attention from the demo to the test suite.

It also changes the first question asked in discovery. Not what the approval screen should show, but this: when an employee and their manager disagree about the available balance, who is right, and how will the system demonstrate it.

The honest limit

The identity as written here is the simple case. Real entitlement rules get worse. Multiple leave types with different accrual and carry-over behaviour, part-day requests, time in lieu that accrues from recorded work, entitlements that vary with tenure mid-period, and jurisdictions where a statutory minimum overrides policy. The identity still holds per leave type per period, but allocated becomes a computation rather than a value, and that computation deserves the same treatment as the balance itself.

The four stress cases are the ones I have watched break these systems. They are not a complete list, and I am not claiming they are the four most frequent failures across the industry. Treat them as a floor for acceptance rather than a ceiling.

And none of this makes the screens unimportant. A balance nobody can reach through a usable interface is not a product. The claim is narrower. The screens are the part that will be noticed when they are wrong and fixed within a week. The balance is the part that will be trusted while it is wrong, and by the time anyone notices it usually cannot be fixed at all.

FAQ

What is the single arithmetic identity in a leave system? Available equals allocated, less used, less pending. Allocated is the entitlement for the period, used is leave taken and finalised, pending is requested but unresolved. Pending is deducted so an employee cannot commit the same day twice while an approval waits in a queue. Every screen in the system is either a view of that identity or an operation that changes one of its terms.

Why is a click-through acceptance checklist insufficient? Because a user journey is a happy path with a name. Submitting a request and seeing a balance decrease passes on a system that also double-counts retried approvals, miscredits cancellations after a calendar change, and cannot reconstruct last year. The failures live in concurrency, retrospective change and period boundaries, and no list of journeys visits any of them.

What happens when a calendar changes underneath an existing request? The number of days the request consumed and the number it would consume today diverge. On cancellation, a system that recomputes from the current calendar credits or debits the employee for an administrative action they never saw, and the difference stays in the balance permanently. The correct behaviour is a policy decision that has to be made explicitly rather than inherited from whichever recomputation the code happens to perform.

How should an administrative adjustment be recorded? As an operation with an amount, a reason, an author and an effective date, recorded alongside every other change to the balance. Editing the balance directly produces a figure that cannot be derived or explained, and any dispute about it has no resolution. The adjustment is a feature of the system, not an exception to it.

What should go into the contract for this kind of build? The identity itself, defined so that two people compute the same available figure from the same facts. Then the stress cases as acceptance criteria with expected outcomes agreed in advance, a requirement that any past balance be explainable at a date, and an automated concurrency test on the approval transition. Those four items constrain the architecture more than the entire module list does.

Does this mean the screens do not matter? They matter, and they still get built. The difference is where the engineering care and the acceptance attention go. A broken screen is visible and gets fixed quickly. A balance that is quietly wrong is trusted, propagates into payroll and planning, and by the time it is questioned the system usually has no way to explain how it arrived at the figure.