Internal Management System

The system

The code is sliced by feature rather than by technical layer. Each workspace owns its domain rules, its validation, its permission checks and its components in one place, so a change to how attendance works stays inside attendance instead of rippling through a shared controllers folder.

Underneath, everything leans on one organization module — people, departments, teams — because every other workspace is ultimately about someone or something that belongs to the company. Getting that spine right early is what let the later workspaces be small.

Writes go through a single wrapper that resolves the caller, checks authority, runs the mutation and records the audit event inside one transaction. A state change and the record of that change either both land or neither does. An audit trail that can silently disagree with the data it describes is worse than no audit trail, because it is trusted.

Who may do what

Authorization is its own module rather than a check scattered through routes. It resolves what a caller may do from 32 named permissions, seven baseline profiles, and any direct grants layered on top of a profile for the person who is a genuine exception.

The check runs on the server on every request. Route gating is the first boundary, not the only one — a workspace the navigation never offers is still refused when it is requested directly, and hiding a control is treated as presentation, never as protection.

It is also the one part of the system carrying a regression suite of its own. Permission logic is exactly the code where a quiet change is expensive and invisible: nothing breaks, nothing errors, and someone can suddenly read a colleague's medical record. The tests exist so that a widened boundary fails loudly instead.

What it actually does

Nine workspaces are in internal use, each replacing something that used to be printed, photocopied or kept in a spreadsheet on one person's machine.

Two details shaped more of the build than their size suggests. Intake is bilingual, Urdu and English, because the people closest to a hazard are not always the people most comfortable reporting it in English — and a safety system that quietly filters by language is not collecting the reports that matter most.

The second is that spreadsheets had to keep working. Registers import from and export to workbooks, and reports print to a clean A4 page, because the system has to interoperate with the paper process it is replacing rather than demand everyone abandon it on the same day.

A month at a glance

The attendance and utilisation workspaces are the same shape: one entry per subject per day, folded into a month-wide grid an operations lead can read across in a single pass.

The grid deliberately stops at recording. It says which state an asset or a person was in on each day; it does not compute a utilisation percentage, an efficiency score or a ranking. Those numbers would be easy to add and easy to misread, and nobody has asked for a measure whose definition has not been agreed.

What the tests hold

There are 33 committed test files, and they sit beside the code they cover rather than in a separate tree — a workspace's domain rules, validation, permissions and workflow tests live in the workspace.

They run on Node's own test runner, so the suite adds no test framework to the dependency list. That was a deliberate constraint on a system one person maintains: every dependency is something that will eventually need upgrading, and a test suite is not worth a second toolchain.

The shapes worth naming are the permission tests on every workspace that has a boundary, the round-trip tests on workbook import and export, and one end-to-end test that walks a record through its whole lifecycle. Coverage is not measured, so no coverage figure appears here.

How it is served

The application sits behind a reverse proxy that terminates TLS, and talks to PostgreSQL through a bounded connection pool. Sessions are database-backed, sign-in is rate-limited and bot-checked, and passwords are stored with a salted key-derivation function rather than a plain hash.

Private media never has a public URL. Field photographs, portraits and medical certificates are held in a private bucket and reached only through in-app routes that re-check the caller's permissions on the way past — a link that leaks is a link that stops working for whoever it leaked to.

Photographs arrive from phones, which means they arrive large and occasionally in formats a browser will not display. They are converted and resized on upload, so the storage cost and the load time are settled once at intake rather than paid on every read.

How it grew

The order was driven by which piece of paper was costing the most, not by which module was most interesting to build.

Reporting came first because an incident form that goes missing is the one failure with a genuine safety cost. The organization spine came second, because every workspace after it needed somewhere for a person to belong. The permission model was hardened once there was enough in the system to be worth protecting properly.

The tradeoff

My strongest engineering evidence on this project sits in exactly the places I cannot show: domain rules, permission resolution, transactional behaviour and the relationships between records.

On this page I would rather describe those honestly and abstractly than manufacture a realistic-looking screen full of invented employees. A fake dashboard would show more and prove less, and anyone who has built one of these can tell the difference.

What holds, and what does not

The previous version of this case study said the repository had no committed tests. That is no longer true — there are 33 files — so the claim has been replaced rather than quietly dropped.

What is genuinely outstanding is narrower and less flattering. Schema reaches the database by push rather than through committed, versioned migrations, which means there is no migration history to review or roll back. The tests run when someone runs them; no continuous integration runs them on a change. Both are known, both are mine, and neither is hard — they are simply not done.

Current status

The system is deployed internally and in daily use across its nine workspaces, and remains under active development.

The rows below separate what is in place from what is not, on the same terms as the section above: nothing planned is listed as though it were delivered.