Read me first

Welcome. This document is for the person opening this project for the very first time. It assumes you know schools, not software. There is no code here and no technical jargon; where a technical word is unavoidable it is explained in plain English, and there is a glossary at the end.

One promise up front: this document describes only what the software actually does today. Where something is planned, partly built, or built but not switched on, it says so plainly. Nothing here is a sales pitch.

---

1. Who this is for

This is a student information system — the central record-keeping system a school or district runs on. It is built for the people who keep a school's records straight:

• District and school administrators, who need to see how the district is doing and stay on top of legal deadlines.
• Teachers, who take attendance and record grades for the classes they teach.
• School nurses, who keep health records for students.
• Counsellors and special education case managers, who look after students with individualised education programmes.
• Parents and guardians, who want to see how their own children are doing.

You do not need to be technical to use it. You do need someone technical, once, to install it and connect it to your sign-in system — that part is covered in a separate document.

If you are evaluating this to decide whether it could work for your school, start with sections 2, 3 and 4, then look at the walkthrough screenshots described in section 12.

---

2. What it does

In a few sentences: it holds your students' records in one place, and shows each person only the part of that record their job requires.

Concretely, today, the system lets you:

• Keep a register of students, the schools they attend, and the classes they are enrolled in.
• Take daily attendance, class by class.
• Record grades against assignments in a gradebook.
• Keep health records — allergies, medical alerts, the date of a student's last examination.
• Track individualised education programmes: their goals, the services a student receives, the accommodations they are entitled to, and the legal deadlines attached to them.
• Show families their own children's attendance, grades, schedule, and a plain-language summary of any special education plan.
• Let families and staff send messages to each other, kept with the student's record rather than in personal email.
• Give administrators a single overview screen: how many students are enrolled, how attendance is tracking, which behaviour alerts are open, and which deadlines are overdue or approaching.

Everything is available in English and Spanish, switchable from the top of any screen.

What it does not do yet. Be aware of these before you plan around it:

• There is no report card or transcript generation in the screens today.
• There is no timetable or master-schedule builder in the screens today.
• There is no fee or tuition billing in the screens today.
• Predictive "early warning" scoring exists in the codebase but is not switched on in the version you can run. The system works normally without it and simply omits those scores.
• Some capabilities exist in the system's programming interface but have no screen yet — state reporting extracts, scheduling, and invoicing among them. A developer can reach them; a user with a browser cannot.

---

3. The domain: what a student information system is

If you have not worked in school administration, here is the setting.

Every school has to keep records: who its students are, whether they turned up, what grades they earned, who to contact in an emergency. Historically each of those lived in a different place — a register, a mark book, a filing cabinet, a spreadsheet. A student information system, usually shortened to SIS, is the single system that holds all of it and keeps the copies in step.

Three things make this harder than ordinary record-keeping, and they shape the whole design of this software:

It is legally regulated. In the United States, student records are governed by a federal law usually called FERPA, which controls who may see a student's record and requires schools to be able to show who looked at what. Students with disabilities are covered by a second law, usually called IDEA, which requires a written plan — an individualised education programme, or IEP — reviewed on a fixed legal timetable. Missing an IEP deadline is not an administrative slip; it is a compliance failure with real consequences for the district.

Different people are entitled to different parts of the record. A teacher needs to know that a student gets extra time on assessments. That same teacher has no business reading the student's full psychological evaluation. A nurse needs allergies; a nurse does not need grades. A parent is entitled to everything about their own child and nothing at all about anyone else's. This is not a preference — it is a legal requirement, and you will see it enforced everywhere in this system.

The same fact is needed in many places. When a teacher marks a student absent, that one mark has to reach the attendance rate the principal sees, the record the parent reads, and any report the district files. If those are separate systems, they drift apart. Here they are one record, written once.

---

4. Where it fits

The kinds of organisations this suits. A single school, a multi-school district, or a private or international school network. The system is built around one district at a time, with schools inside it; every record belongs to a district and is kept strictly separate from any other district's records.

Who signs in. Staff and families sign in through a separate identity service rather than with a password stored in this system. In practice that means your users sign in the same way they sign in to your other systems, and this software never stores or sees a password. Setting that connection up is a one-time technical task.

What it connects to today. Honestly: very little, and you should plan accordingly. The system runs as a self-contained whole — the application and its database. There is no live connection to a learning management system, a state reporting system, a payment provider, or an email gateway in the version you can run today. Groundwork exists in the codebase for the common education data standards, and there are ways for a developer to extract data, but there is no working, configured integration you can switch on from a settings screen.

If you need to exchange data with another system, treat that as development work, not configuration.

---

5. First run

When you open the system for the very first time, this is what to do.

If you are trying the preview. The preview version arrives already filled with invented demonstration data — a fictional district, about a hundred and twenty invented students, their classes, attendance and grades. Nothing in it is real. You can click anything without consequence. Sign in, and you will land on the administrator's overview screen. The single most useful thing to do first is to look at the View as control at the top right and use it to look at the system as a teacher, a nurse, a counsellor, and a parent in turn. In about two minutes that shows you the whole shape of the product and the way each role is fenced off from the others.

If you are setting up a real system. Your first run is different and there is one correct order:

1. Have your technical person deploy the system and connect it to your sign-in service.
2. Run the first-use setup, which creates your district, your first school, and your first administrator account. This is described in production-setup.md. It is a one-time step and it is deliberately destructive — it is meant for a system nobody has used yet.
3. Sign in as that first administrator.
4. Only then start adding real people and real students.

Do not load real student data into a system that still contains demonstration data. Clear it first — see section 14.

---

6. Setting up

Setting up a real environment happens in this order. Steps 1 and 2 need a technical person; the rest are yours.

Step 1 — Deploy the software. The system needs somewhere to run and a database. This is a technical task, done once.

Step 2 — Connect your sign-in service. The system does not manage passwords. It relies on a separate identity service to confirm who someone is. Your technical person registers this system with that service. Until this is done, nobody can sign in.

Step 3 — Create your district and first administrator. Run the first-use setup described in production-setup.md. You will need your district's name, your state code, the name of your first school, and the email address of the person who will be your first administrator. That must be a real person who can sign in through your identity service.

Step 4 — Add your schools. Add the remaining schools in your district.

Step 5 — Add staff and give them roles. Every person needs a role, because the role decides what they see. Roles are covered in section 11.

Step 6 — Add students and enrol them. Each student belongs to a school and is enrolled in the classes they take.

Step 7 — Link families to their children. A parent or guardian sees a child only if that link exists. This is the step most often missed, and the symptom is a parent signing in successfully and seeing an empty page.

About bulk loading. There is no import screen for uploading a spreadsheet of students. For a district-sized migration, expect your technical person to load the data directly. Plan for that; do not assume you can upload a file yourself.

---

7. Day to day

What routine use actually looks like, by role.

A teacher signs in and sees only the classes they teach, each with its course, period, room, and student count. Opening a class gives four things: take attendance for today; record scores in the gradebook, typed straight into the grid and saved as you go; check accommodations, which lists what a student in that class is entitled to — extra time and so on — without showing the full special education plan; and message a family.

For most teachers the daily routine is: open the class, mark attendance, and enter any marks. That is it.

An administrator signs in to the operations overview: current enrolment, attendance across the last thirty days, open behaviour alerts, and the compliance list. The compliance list is the one to read every day — it names the students whose IEP deadlines are overdue or coming due, so nothing has to be chased by hand. The View as control lets an administrator look at the system as any other role, read-only, to answer questions like "what does this parent actually see?" without borrowing anyone's sign-in.

A nurse opens the health office, chooses a student, and reads or updates allergies, medical alerts, and the last examination date. The nurse sees health information only — no grades, no discipline records.

A counsellor works from a caseload: the students they are responsible for, each with the state of their special education plan — goals, services, accommodations — and whether a review or evaluation has slipped overdue. Attendance and grades sit alongside, because the real question is usually whether a student is quietly drifting, and that is rarely visible in one number.

A parent or guardian sees their own children, and for each: attendance, recent absences, current grades by course, the schedule, a plain-language summary of any special education plan, and messages from staff.

---

8. Ongoing care

Periodic work, roughly in order of how often it matters.

Daily. Someone should look at the compliance list on the administrator's overview. Deadlines are the thing this system is best at surfacing and the thing most expensive to miss.

Each term. Set up the new academic year, its grading periods, courses and classes before term begins, and enrol students into them. Attendance and grades attach to classes, so nothing can be recorded until this exists.

Backups — read this one. The system does not back itself up, and the preview version deliberately throws its data away when it stops. For any real installation, your technical person must arrange regular database backups and, just as importantly, must test restoring one. An untested backup is not a backup. This is the single biggest operational risk in running this software and it is entirely on you.

Audit records. Every access to a student's record is logged, including every use of the "View as" feature. These records accumulate and are your evidence of compliance. Decide how long you keep them and make sure they are covered by your backups.

Leavers. When staff leave, remove their access promptly. Because sign-in is handled by your identity service, removing someone there is what actually stops them getting in.

Upgrades. New versions arrive as software updates applied by your technical person. Read the release notes before applying one to a live system, and take a backup first.

---

9. Glossary

• Accommodation — an adjustment a student is legally entitled to, such as extra time on assessments. Teachers see the accommodations relevant to their teaching.
• Attendance rate — the share of expected attendances actually recorded as present over a period.
• Behaviour alert — a flag raised about a student's conduct, which stays open until somebody resolves it.
• Caseload — the group of students a counsellor or case manager is responsible for.
• District — the administrative body that runs one or more schools. In this system every record belongs to exactly one district and is invisible to any other.
• Enrolment — the record that a student attends a school, or is a member of a class.
• FERPA — the US federal law governing who may see a student's education record.
• Gradebook — the grid of assignments and scores for a class.
• Guardian — an adult responsible for a student, who may or may not be a parent. Treated the same as a parent by this system.
• IDEA — the US federal law covering the education of students with disabilities.
• IEP (individualised education programme) — the written plan for a student with a disability, with goals, services and accommodations, reviewed on a legal timetable.
• Identity service — the separate system that confirms who someone is when they sign in. This software never stores passwords.
• Section — one specific class: a course taught in a particular period and room. Students are enrolled in sections.
• SIS — student information system. This software.
• View as — the read-only feature letting an administrator see the system through another person's role.

---

10. The other documents

Everything in user-docs/ is written for you rather than for a developer.

• READ-ME-FIRST.md — this document. Start here.
• production-setup.md — the runbook for preparing a brand-new real installation: creating your district, your first school and your first administrator. Read it before you set up anything real. It describes a deliberately destructive one-time step, so read its warnings properly.

Technical documents live elsewhere in the project and are written for developers. You should not need them.

---

11. Who can do what

Every person has a role, and the role decides what they see. Roles are set when an account is created.

Role	Sees
District administrator	The whole district: enrolment, attendance, compliance, plus "View as"
School administrator	The same district-wide overview as a district administrator. Today this screen is not narrowed to a single school — worth knowing before you hand the role out
Teacher	Only the classes they teach, and the students in them
Nurse	Health records only — no grades, no discipline records
Counsellor	Their caseload, including special education plans, attendance and grades
Parent or guardian	Their own children only

Two things worth knowing. A person with no role assigned can sign in but sees nothing useful — that is deliberate, and it is the usual explanation for "I signed in and the page is empty". And "View as" is strictly read-only: an administrator using it cannot change anything, cannot leave their own district, and every use is written to the audit log.

---

12. The demonstration data

The preview version ships already filled with invented data: a fictional district, three schools, around a hundred and twenty students with classes, attendance, grades, health records and special education plans, plus a handful of messages.

None of it is real. The names are invented. Click anything.

Two things to know:

• The preview forgets everything when it stops. Restart it and you are back to the same starting point. That is intentional — it makes the preview safe to experiment in.
• To start fresh with real data, do not reuse the preview. Deploy a proper installation and run the first-use setup in production-setup.md, which clears the database and loads only the minimum a working system needs. It never creates fictional records.

A set of annotated screenshots of every screen lives in the project's docs/walkthrough-screenshots/ folder, with a narration script explaining each one. That is the fastest way to see the whole product without installing anything.

---

13. Common questions

I signed in and the page is empty. Almost always no role has been assigned to your account, or — if you are a parent — no children have been linked to you. Ask your administrator.

A parent says they cannot see their child. The family-to-child link is missing. It is the most commonly missed setup step.

Why does a yellow bar say "Viewing as"? An administrator is using the read-only tour to see the system as someone else. Everything on screen is that person's view, nothing can be changed, and the action is logged.

Can I upload a spreadsheet of students? Not from a screen. Bulk loading is a technical task today.

Can teachers see a student's full special education plan? No, by design. They see the accommodations relevant to their teaching. The full plan is for the counsellor or case manager, and a plain-language summary is available to the family.

Where are report cards and transcripts? Not built yet. See section 2.

Is my data backed up? Not unless your technical person has arranged it. See section 8.

Can I run this for several districts at once? Each installation is built around a single district. Several districts means several installations.

---

14. Where to get help

This software is open source and community-supported. There is no vendor support desk.

Go to wbsp.ai. It is the community behind this project, and it is the right place to ask questions, report something that looks wrong, suggest what the system should do next, or find people who can adapt it for your organisation.

That last point matters. What you have is a core system: it does the job, but it is deliberately plain — no styling, no branding, none of the particular language your school uses. It is meant as a foundation to build on. If you have domain knowledge and access to AI tools you can shape it yourself; if not, the community is where you find someone who can. It is also worth browsing what others have already built, because someone may have made a version much closer to what you need.