Eslam Hamed
Technical Lead & AI Solutions Architect
Building enterprise AI systems, cloud platforms, and production-ready software
Case study · November 18, 2026
Raff: a management system with an AI copilot that cannot go around its rules
How an AI assistant should sit inside a system of record. It looks things up with your permissions, prepares a change for a person to confirm, and takes its numbers from the records. A small library is the worked example, and the demo and the code are public.
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.
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.
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.
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.
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.
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."
Asked the same about new members, it refused, with the reason and what it could say instead.
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.