The app was 'built' but a quiz did not work anywhere

You are told a product is built. The plan says so and the database has a place for everything. Then somebody sits down and uses it, and a whole half of it does not work. Before you pay for a rebuild, it is worth knowing which half, and how you would have found out.

That was a children’s learning app. Planning its rebuild, we checked every existing screen against the live server to see what could be built straight away. The parent’s side came out at thirty-four of thirty-seven screens that the server could supply that day. The child’s side came out at none of eighteen.

What was actually going on

All seventy-five things the server could do were for parents. There was no way for a child’s paired tablet to sign in, no way for it to read the lessons given to it, and nothing anywhere that recorded a quiz attempt. Taking a quiz did not work anywhere in the product, including in the parent’s own web portal.

The database described a complete product. It even had an empty space reserved for the tablet’s sign-in credential, waiting for a scheme nobody had written. About forty per cent of the product had no server behind it.

Nothing had lied. The database had been designed up front, in one pass, from the full feature list, which is a reasonable way to work. It gives you a database that describes the finished product and a server that describes whatever has been built so far, with nothing comparing the two. The plan said the feature existed. The database had a place for it. Seventy-five server functions read like good coverage.

The best clue was sitting in the automated tests, in a comment. A test needed a task that had been given to a child but not yet handed in. It could not create one through the server, so it wrote one straight into the database, with a note explaining that the server could not produce that state. That note was a defect report, and several people had read it as a remark about test convenience.

The cause was one function doing two jobs. The step that assigned a task also submitted it. That was a documented shortcut, taken when no child’s app existed to do the submitting. Once a real parent used it, assigning a task put it straight into the parent’s own review list, already handed in, and the child’s list of jobs could never contain anything.

What we changed

Tasks are now created in an open state, with the old two-in-one behaviour kept behind an explicit switch for the testing case it was written for. Before the child’s app could start at all, sixteen missing server functions had to be built, and the rebuild was planned around that list rather than around the plan.

What it did not fix

The plan itself had also been wrong more often than the code. A screen design showed lessons edited section by section; lessons are stored as a single block of text, so building it would have meant a change to the database that nobody had asked for. A design used two of the three bundled typefaces, so every reading screen was specified in the wrong one. In both cases the older document had been treated as the authority.

The pattern, for anyone about to rebuild or extend a system

Audit by what a person does, not by what exists. Walk each screen, press each control, and name what answers it. An inventory of what you have cannot tell you what is missing.

Treat plans and databases as intentions. Only the running system is a fact. And when a shortcut is taken, write down the event that ends it and put the note where that event will happen, because the note in the shortcut itself will only be read by the people maintaining the shortcut.

Checking costs half an hour before a piece of work and saves days inside it. Here it turned a rebuild that would have stalled on its first screen into one that built the missing sixteen first.

Where this ends up

Reading the running system before planning against it is the first move in replacing anything a business still uses, and it is where most of the surprises are. What that survey covers, and how a cutover is staged afterwards, is under enterprise software modernisation.