What breaks when you build a school management system — the failures that show up every time

Walk into almost any school office and you'll find the same thing: software everyone quietly hates. Attendance takes four clicks and two menus. The report the principal actually needs doesn't exist, so someone exports to Excel every Friday. Parents can't see anything on their phones. The annual rollover to next year's classes is a spreadsheet and a prayer.

So eventually someone decides to just build their own — these days, by pointing an AI agent at it. "Build me a school management system." It's one of the most reliably broken prompts there is. The agent generates the modules you'd expect — attendance, grades, fees, a parent portal — and ships something that demos beautifully. Then a real school touches it, and the floor gives way in the same eight places every single time.

We've built these for real schools, more than once, so this isn't a guess about what might go wrong. It's the list of what does — and it's worth understanding before you write (or generate) a line, because every one of these is a rebuild if you catch it late.

Failure 1 — Guardians stored as a text field

This is the most common and the most expensive. The agent puts parent_name and parent_phone columns on the student and moves on. Then reality arrives:

• A family has two children in the school — now their contact details are duplicated across two records and drift out of sync the first time a phone number changes.
• A child has two guardians (mother and father, or a sponsor) — there's nowhere to put the second one.
• The school wants to message "all guardians of Grade 7" — impossible, because guardians aren't entities you can query; they're strings glued to students.
• A guardian opts out of fee reminders — there's no consent flag, so they keep getting them, and now you have an angry parent and possibly a compliance problem.

A guardian is a first-class entity with a many-to-many link to students, a relationship type, a primary-contact flag, and consent. Flatten it and you will rebuild it — usually mid-migration, with live data, which is the worst possible time.

Failure 2 — A flat fee with no installments or concessions

The agent models fees as amount_due on the student. No real school bills that way. They bill in structures with installments (Term 1, Term 2, Term 3), and they grant concessions — sibling discounts, scholarships, staff-ward waivers, hardship adjustments — each of which needs a reason and an approver for the audit trail.

The day the school explains how they actually charge — "siblings get 15%, staff kids are free, transport is separate and optional, and the second installment has a late fee after the 10th" — a flat fee table collapses. Fees are not a number; they're a small billing engine, and they're the module the accountant lives in every day.

Failure 3 — The daily loop is buried in menus

Teachers mark attendance every period. Accountants take fee payments all day. These are the highest-frequency actions in the building, and the agent treats them like any other CRUD screen — three menus deep, a full page load, no keyboard shortcuts.

Click-depth on the daily loop is the number-one reason schools abandon software they already paid for. It doesn't matter how good the dashboards look if marking a register is slower than the paper one it replaced. Staff will route around the system, the data goes stale, and within a term the software is shelfware.

Failure 4 — No concept of the academic year

The agent builds a system frozen in time. There's no promotion (moving a cohort up a grade at year-end), no rollover (new year, new fee structures, new sections, archived old ones), no re-admission, no alumni. It works beautifully for exactly one academic year, and then every July someone is hand-editing the database to move 400 students up a grade. A school is a cycle, not a snapshot, and if "next year" isn't designed in from the start, you've built a system with a one-year shelf life.

Failure 5 — A data import that corrupts silently

Schools never start empty. They arrive with years of records in spreadsheets and whatever system they're leaving. The agent builds a happy-path importer that assumes clean data. Real data is never clean: duplicate admission numbers, guardians in the wrong column, dates in three formats, half-empty rows.

A good import rejects bad rows, logs every error with a row reference, and lets you fix and re-run. The agent's version accepts everything and silently mangles 4% of your records — which you discover in March when a parent asks why their child's fee history is wrong. A silent import that "succeeds" is worse than one that loudly refuses.

Failure 6 — Permissions enforced in the UI only

The agent hides buttons the current role shouldn't use and considers the job done. But the data layer is wide open: a guardian increments the student ID in the URL and reads another family's records; a teacher hits an API route directly and sees the fee ledger. The most embarrassing school-software bug there is, and it's a direct consequence of treating permissions as a front-end concern instead of scoping every query to the institution, the campus, and the role at the data layer.

Failure 7 — Reports that don't match what the school needs

The agent builds the reports that were easy to build — a list of students, a count of classes. The school needs defaulter lists, attendance summaries by class, collection reports for the board, exam analysis. So they export raw data to Excel every week and build those reports by hand, which is the clearest possible signal that the software failed at its actual job. Worse, the agent's reports often read from a separate denormalized table that drifts out of sync with the live records, so the numbers are subtly wrong.

Failure 8 — A parent portal nobody can use on a phone

Most parents will only ever open this on a phone. The agent builds a desktop layout — wide tables, hover menus — and squeezes it onto a small screen. Parents can't pay a fee, can't read an announcement, can't see attendance, so they call the office instead, and the school is now doing more manual work than before the software existed.

And the quiet one — over-building the wrong half

While missing all of the above, the agent often adds what nobody asked for: a transport module with route optimization, a hostel system, a library with barcode scanning, an HR payroll engine. These are real modules in big deployments, but bolting them onto a first build that can't even mark attendance properly is how you get a system that's simultaneously over-scoped and unusable — bloated where it doesn't matter, hollow where it does.

Why an agent walks into every one of these

It's not that the agent can't code — it's that it has never run a school. It has never sat with a registrar during admissions week, never watched a migration land guardian data in the wrong model, never had a teacher complain that attendance takes too long. It has no operational model of what a school system does or where it fails, so it builds the statistical average of every tutorial and starter repo it has seen — and the average school system is a toy.

You can't prompt your way out of this, because the problem isn't the prompt. It's missing knowledge, and the only fix is to supply it.

What a system that survives a real school does instead

The antidote is boring and specific: model guardians and fees as real entities, make the daily loop one or two clicks, design the academic year from day one, validate every import, enforce permissions at the data layer, build the reports the school actually exports to Excel, and ship a mobile-first parent portal. None of it is exotic — it's just known, by people who've built these before.

If you want the full module spec, we wrote what a real school management system actually includes; for the build sequence, how to build one without shipping a toy; and if you're still deciding whether to build at all, build vs buy a school management system.

That's the entire job of the School Management planner: it front-loads these decisions and forces your coding agent through them before it writes code, with every failure above baked in as something the spec is not allowed to make. You can see a real school system one of these planners built and click through it — the proof isn't a claim, it's the working product.