Every management system is being asked to grow an AI assistant. The easy version is a chat box beside the product, which can either do nothing or do too much. Raff is my worked answer to how an assistant should sit inside one. The example is a small library's system, because everybody already knows its rules. What carries over to any system of record is the Copilot: it looks things up with your permissions, prepares a change for you to confirm, and answers questions about the figures. In all three, the product has the last word, not the model.

The staff dashboard with the Copilot panel open. The request reads: Borrow The Hobbit for Maya Hassan. Under it are a card for the member, a card for the book, and a Borrow card naming copy CP-0100, the member and the due date, with the line 'Nothing changes until you confirm. Expires in 10 minutes.' and a Confirm and a Cancel button
Staff ask in plain words. The Copilot finds the member and the book, then prepares the loan as a card. Nothing has changed yet: the loan is made only when a person presses Confirm. Every screen on this page is the live demo, on generated data.

Context

Raff (رف, Arabic for shelf) runs a small community library: a catalog of books and their physical copies, borrowing and returning at a desk, holds and renewals, two roles with their own screens, a dashboard and an activity log. It started as a time-boxed brief for a mini library management system. I used the brief to answer a wider question, because a library is a system of record in miniature. It has things, people, transactions between them, rules about who may do what, and a history that has to stay true. Swap the books for assets, tickets, stock or appointments and the shape is the same.

The constraint

An assistant inside a system of record can fail in three ways that a chat box beside it cannot. It can state something about the records that is not true. It can show or do something the person asking is not allowed to. It can change something nobody approved. A prompt that asks the model to behave is a request, and none of the three can rest on a request.

So before any code I set one rule for the product. The AI exposes and operates capabilities that already exist in the product. It does not introduce new business workflows. No fines because the AI could charge them, no procurement because a manager might ask, no messaging because an assistant could send reminders. If the pages cannot do it, the Copilot cannot either.

The decisions that mattered

  • The rules sit below the assistant. "A copy can be on one loan at a time" is a unique index in PostgreSQL, not a line in a prompt, and a test races two real connections for the same copy: one gets the loan, the other a refusal. The Copilot's borrow runs through the same service the pages call, so it meets the same rule.
  • The model never says who is asking. Identity comes from the signed-in session. The person's role picks the assistant they get: its instructions, its tools and its reach. A member's assistant has five tools, all read-only, and the one that lists loans takes no member id, so there is nothing for the model to change it to. Staff get fourteen. A tool call carrying a parameter the tool does not define is rejected.
  • It prepares; a person confirms. The model cannot lend or return a book. It can prepare one, which stores a proposal: tied to the person who asked, good once, and gone after ten minutes. Confirm locks that proposal's row, so two confirms at once make one loan, and then makes the change through the product's own service. If the service refuses, nothing is kept. The model is told afterwards how it ended, and its instructions forbid it from saying a loan was made.
  • Every number has to come from a lookup. Before a reply is shown, code compares each run of digits in it with the lookup results and the person's own words. Ids do not count, and the instructions themselves contain no digits. A reply that fails gets one chance to correct itself. If that fails too, the person gets the lookup results as plain sentences instead.
  • Figures are requests, not SQL. For questions about how the library is used, the model picks a metric, a grouping, filters, a period and a comparison from a fixed catalogue. The server runs fixed statements and works out the shares, changes and totals, so the model never has to calculate one.
  • A forecast is measured, or refused. The method is plain: the same month a year earlier, times the trend. Its range is not assumed. The same method is run on past months and compared with what happened, and how far it missed sets the range. A series that is too short, too sparse or too erratic gets a refusal that says what the records have and what a forecast would need.
A request in plain words leads to lookups that run as the signed-in person; the model prepares a proposal that is saved for that person for ten minutes; a person presses Confirm; the product's own service makes the change; the database allows one active loan per copy or refuses; the activity log records who did it and that it came through the Copilot.Requestin plain words, from a member of staffLookupsrun as that person, within their roleProposalsaved for that person, for ten minutesConfirma person presses it; the model cannotThe product's own servicethe same code the pages callDatabaseone active loan per copy, or a refusalActivity logwho did it, marked as via the Copilot
How a change gets made. The model reaches the first three steps. The dashed one belongs to a person, and everything after it is the product doing what it does for any page.

What it looks like

The same question gets two answers, because it reaches two different sets of tools. Asked "Who has The Hobbit right now?", the staff Copilot names the borrower, the copy and when it is due. The member's assistant says it cannot see who has borrowed a book, and gives what a member may know: one copy is out, due back on 1 December, and two are on the shelf.

The Staff Copilot answering 'Who has The Hobbit right now?': a card for the book with 2 of 3 copies available, a card showing the loan of copy CP-0099 to Grace Esposito, due Dec 1, 2026, and the reply that she has the copy, that it is due back on 1 Dec 2026, and that the other 2 copies are available
Staff: the borrower, the copy and the due date, each taken from a lookup.
The member's Library assistant answering the same question: a card for The Hobbit listing its three copies, one borrowed and due back Dec 1, 2026 with no borrower's name and two available, and the reply 'I cannot see who has borrowed a book, as I only see your own account details', followed by how many copies are borrowed and available
A member, same question. The tools that would name a borrower are not in this assistant at all.

Pressing Confirm on the card at the top of this page made the loan, and the product recorded it the way it records everything else. The copy was then returned at the desk, without the Copilot.

The Activity page. The newest line reads 'Returned The Hobbit (CP-0100) from Maya Hassan', by Demo Staff. The next reads 'Borrowed The Hobbit (CP-0100) to Maya Hassan, due 2 Dec 2026', by Demo Staff, with a Copilot mark. The two older lines below, by another member of staff, have no mark
One log for every action. The loan confirmed through the Copilot is an ordinary line with the name of the person who confirmed it, plus a Copilot mark. The return made at the desk has none.

A question about the figures comes back as a chart, a table and a short reading. Every figure in the reading, shares included, is in the table. The server worked them out, and the number check holds the reply to them.

The Staff Copilot answering 'Which five categories were borrowed most last quarter?': a bar chart and a table of loans by category for Q3 2026, led by Children with 107 loans and a 16.3% share and Fiction with 103, a total of 657, and a reply that lists the same five figures
Loans by category for the last full quarter. The model chose the metric, the grouping and the period; the server ran the query and computed the shares.

Asked what to expect over the next three months, it gave 240 loans for November with a likely range of 214 to 297, and said where the range came from: it "was measured by how far the same method missed when tested on past months."

The top of a forecast answer: a line chart of monthly loans for the past year, then three forecast months drawn dashed inside a shaded likely range. The subtitle reads: Nov 2026 to Jan 2027, from 35 months of history, Dec 2023 to Oct 2026, typical error 12.4%
The top of the forecast answer. The subtitle says what it rests on: 35 months of history and a typical error of 12.4%. The table and the reply continue below the chart.

Asked the same about new members, it refused, with the reason and what it could say instead.

The Staff Copilot asked to forecast new members for six months. It shows a small table, New members trend, with 74 in the last 12 months against 63 in the 12 before, and replies that a forecast cannot be made because the records average 6.2 new members a month where a forecast needs at least 10, then gives the trend instead
A refusal with its numbers: what the records have, what a forecast would need, and the trend in its place.

And when the request is for something the product does not do, it says so. To "Waive Maya Hassan's late fees and email her a reminder" it answered: "I cannot waive late fees or email members, as the library app does not have features for handling fines, payments, or sending messages."

What shipped

  • A catalog of books and their physical copies, with ISBN lookup and search. A book with loan history is archived, never deleted.
  • Borrow and return at a desk by copy code, due dates, overdue tracking, and the loan history of every book and member.
  • Holds and renewals: a line for a book whose copies are all out, a returned copy set aside for the first in line for three days, and renewals a member makes alone, at most twice and not while someone is waiting.
  • Two roles with their own screens, Google sign-in, and a demo sign-in for each role so anyone can try both.
  • A dashboard, and an activity log of every action that marks what came through the Copilot.
  • The Copilot on every page: lookups for members and staff, prepared Borrow and Return for staff, and figures and forecasts for staff.
  • One Docker image that serves the API and the web app, a CI pipeline of four jobs, and a public demo.

How it was built

An AI coding assistant, Claude Code, wrote Raff. I decided what it would be. Before any code I wrote the product definition: the scope rule, the lending model, the two roles, what was out of scope and where to cut. From there every step followed one loop. A brief with an outcome checklist and the exact API contract, which I approved before anything was built. A parallel build, with the backend and the frontend written by separate sessions against that one contract. Then integration: the full set of checks, a rebuild of the Docker stack, a walk through every checklist line in a browser against real data, and live turns against the real model. Then the record: what was decided and why, what is still open, and what went wrong.

Part of the method is enforced by tooling, not by good intentions. A step is not done until every check is green, and a planted error proves the checks can fail. Integration tests run against a real PostgreSQL database and fail, not skip, when it is missing. One hook blocks a secret from being written into a file. Another blocks ending a turn in which a test was weakened, skipped or deleted.

The walks found what the tests had not. Once in four tries the model went silent after its lookups, and the engine's retry had taken its tools away, so it could not take the next step; an empty reply now gets one nudge with the tools still on offer. The forecast ran high: its own past tests showed a median miss of 9% to 20%, so the forecast is now moved by that miss. And the last review, which read the finished work three ways, found no defect in the product and nineteen in what was written about it, among them the claim that the assistant never invents a number. The check compares runs of digits, so a number spelled out in words passes. I would rather say that here than claim more than the code does.

The result is about 25,400 lines of application code and 16,600 lines of tests. The last CI run passed 908 backend tests, the integration ones against PostgreSQL 16, and 293 frontend tests, then built the image.

Result

A working system anyone can open and try, with its code and its build record public. It is a reference build, and that should be said plainly. The library's data is generated: 286 real titles, about 490 copies, 200 members and three years of borrowing. Nobody depends on it, and it runs on a single server. The shortcuts taken for a demo are listed in the repository with their fixes: the activity log is append-only by convention, not by a database rule; the Copilot's rate limit lives in one process's memory; there is no uptime monitoring. The code has had no independent review, so its correctness rests on the tests and the walks. The Copilot does not yet place holds or renew loans, although the pages do, and it says so when asked.

What it demonstrates

Putting an assistant into a system of record is mostly not an AI problem. Permissions, constraints, a confirm step and an audit trail are old tools, and they hold a language model as well as they hold a person, provided the assistant is built to go through them. The other half is method. An AI coding assistant can build a system like this in a day. What makes the result worth trusting is the specification, the checks and the record around it, and that part was mine.

All case studies

More case studies