SamwiseCampus runs institutional administration, teaching, attendance, finance, scheduling, records and certificates from a single application — with every school's data resolved on the server, never chosen in the browser.
It is an owner, administrators, a bursary, teachers, guardians and learners, each seeing a different slice of the same records — and several schools running side by side in one deployment without ever touching each other's data. That shape is what the system is built around.
A tenant is an institution with its own campuses, tiers, timezone, currency and branding. A person's relationship to it is a membership — not a column on their user record — so one account can hold several at once and switch between them.
Role and institution are resolved from the signed-in session on every protected request. The client never sends a tenant or a privilege level, so it has nothing to tamper with. Eighteen named capabilities decide what each workspace may do.
Admissions through to a signed certificate. Enrolment records, attendance registers, gradebooks, timetables, fee structures, invoices, payment review, documents, messaging and awards all live in one schema and share one audit trail.
Deterministic builds, migrations applied during deploy, a rehearsed backup and restore drill, health checks and a handover workspace that proves the deployment is ready before anyone depends on it.
The central rule of the system, and the one everything else is arranged around: an authenticated person never picks their school or their privilege level. The server works it out and refuses the rest.
Client-side role gates are navigation, not security. The workspace routes check the role so a teacher is not offered the bursary screens, which keeps the interface honest and the navigation short. They are a courtesy. Every one of those screens is independently protected on the server, so hiding a link is never the thing standing between a person and another school's records.
The product is organised as workspaces rather than screens. Each is a domain of the API with its own capability boundary, its own records and its own audience — and each appears in the navigation only for the people who have the capability to use it.
The institutional dashboard and first-run experience. It answers what a signed-in person may do next, and it is where a new deployment is brought to life.
Institutional recovery treated as a measurable practice rather than a promise. A quarterly review is scheduled, activated and evidenced.
Attendance is the operational heartbeat: rosters, an acceptance preview before anything is committed, single and bulk marking, and a branded register document.
The export surface. Reporting data leaves the application as a file a school can keep, mail or hand to an inspector — scoped to the institution that asked.
Fee structures become invoices, invoices become payment proofs, and proofs are reviewed by a person with the authority to accept them.
Who is in the institution, what they may do, and the invitation that got them there — including teaching assignments that narrow a teacher to specific classes.
Files live in managed object storage, not in the database. The application holds the metadata, the ownership and the access decision; the file itself is reached through a short-lived signed reference.
One institution's identity governs every document it produces. A register, a roster or a certificate must not carry another school's marks.
Attendance is recorded against a roster rather than a free-form list, so the register a teacher marks and the register a head teacher prints are the same object.
| Step | What happens | Who |
|---|---|---|
| Roster | The learners expected in a class for a session and date, resolved for the institution. | Teaching staff, administrators |
| Preview | An acceptance preview shows what the mark set will do before it is committed. | Teaching staff |
| Mark | A single learner is marked, or the whole register is submitted in bulk. | attendance:manage |
| Brand | The institution's brand profile is applied to the register document. | Resolved automatically |
| Export | The reporting data leaves as a CSV scoped to the institution. | Administrators |
Courses, assignments, submissions and grading schemes, for institutions that grade by continuous assessment and for those that grade on a tertiary scale.
Courses are created for an academic session, students are enrolled against them, and assignments are created inside a course. The eligible-student list is resolved per course rather than offered as a directory dump, so a teacher only ever picks from the people who are actually in front of them.
A gradebook is requested for a course and session, submissions are graded against it, and the grading scheme that produced the total is stored alongside the result. A mark without its scheme is a number nobody can defend a year later.
Institutions on a tertiary tier can save a grading scheme of their own, which the gradebook and the grading bridge then use. The default scheme is not assumed for them and not forced on anyone else.
A bridge from recorded grades to issued awards, so a certificate
reflects the gradebook rather than a transcription of it. Grades
carry grades:manage; courses carry
courses:manage. They are separate grants.
The timetable is built from resources that exist: physical spaces, the staff who teach in them, and the class groups that move between them.
Timetable resources are registered once and entries are created, updated or cancelled against them. Staff resources and staff profiles let a teacher's own load be described without exposing anyone else's.
A class group is a cohort with a roster. Learners are enrolled into it, withdrawn from it or transferred between groups — each transition recorded, so a learner's movement through the institution is reconstructable.
A learner sees their timetable and nothing else. It is the narrowest workspace in the system by design: the smaller the surface, the smaller the thing that can be got wrong.
Reminders are activated as an explicit, recorded action rather than a background timer that quietly starts existing. Scheduled work is a declared job, so it survives a restart and can be inspected.
The school sets what is owed; the guardian says what they paid; the bursary decides whether it counts. Three separate grants, so no one of them can complete the loop alone.
A fee structure is created for an academic session, and an
invoice is generated against a student from it. Structures
carry fees:manage — a teacher does not have it.
A guardian sees only their own learners' invoices and submits
proof of payment against one, under
payments:submit. They cannot mark it approved,
because they do not hold that grant.
Pending payments are reviewed and confirmed or rejected under
payments:review. An approved payment yields a
receipt reference. Reviewing and submitting are deliberately
not the same capability.
Certificates are issued from recorded results, signed by someone with the authority to sign, released to a recipient, and independently verifiable afterwards. A certificate is worth what its verification is worth.
A recipient and an award are chosen, suggestions come from the gradebook, and the certificate is previewed before it is issued. Single and batch issue both exist, so a graduating class does not become an evening of clicking.
A certificate is voided, not edited, and a corrected one is issued as a separate document. The history of what was issued remains intact, which is the only behaviour that survives an audit.
A certificate is released to the recipient and can be sent to them. Being eligible to see an award and having it delivered are separate moments, so a document is never in someone's hands before the school meant it to be.
A verification path confirms an award against the record it was issued from. Signature authority can be delegated and revoked, and the delegation list is itself visible — so it is knowable who could sign for the institution, and when.
Four capabilities sit here rather than one: issuing, signing, verifying and delegating. An institution can let a registrar issue awards, a head of school sign them, and a verifier check them, without any of those three being able to do the other two.
The intake workspace carries a learner from a document on someone's desk to an enrolled person with a guardian attached and a history nobody has to reconstruct.
Nothing is served from a guessable path. A document is opened by asking the application, which checks the capability, checks the institution, and only then produces a signed reference that expires.
Files live in S3-compatible object storage. The database holds the metadata: what it is, who it belongs to, which institution it is scoped to, and whether it has been archived.
Every read produces a signed URL with an expiry. Copies of a link differ from one another and none of them works indefinitely, so a link that leaks in a group chat is of limited use.
A share names its recipient. It can be listed, and it can be revoked — after which the reference stops resolving. Archiving is separate from deleting, so a document leaves the working set without leaving the record.
Attendance registers, enrolment rosters and certificates are produced as PDFs from the same records the screens read, under the institution's own brand. There is no second copy of the truth in a template.
A message centre inside the application, governed by
notifications:manage. Messages are sent, listed,
archived and unarchived — the archive being how a school keeps a
working view short without losing anything.
Transactional email — password resets and account notices — is delivered through a dedicated sending domain with its own SPF and DKIM records, so school correspondence is not sent from an address that anyone else can claim.
A school's register should not go home bearing a default logo. Brand is stored per institution and resolved into every document that institution produces — in a multi-tenant deployment, that is a correctness requirement, not a cosmetic one.
documents:write
Who someone is to the school, and how much authority they hold there. A membership type and an access role are different fields on purpose — a bursar and a head teacher are both staff, and they should not be the same grant.
What someone is in the institution. This is what determines which workspaces are available to them at all.
| Type | Who it is for | Typical surface |
|---|---|---|
| Webmaster | The institution's technical owner. | Branding, handover, resilience, everything below |
| Admin | School administration. | People, enrolment records, reports, timetable |
| Bursary | The finance office. | Fee structures, pending payments, payment review |
| Teacher | Teaching staff. | Attendance, gradebook, courses, own classes |
| Staff | Non-teaching members of staff. | Schedules and resources within their role |
| Student | Learners. | Own timetable |
| Guardian | Parents and guardians. | Own learners' invoices and certificates |
How much authority a membership carries. Owner, admin, staff and read-only — applied on top of the membership type, and evaluated on the server for every request.
Eighteen named grants. A procedure asserts the one it needs; nothing is implied by holding a neighbouring grant.
| Capability | What it authorises |
|---|---|
institution:read |
Reading the institution's own profile and settings. |
membership:manage |
Inviting, changing, deactivating and reactivating memberships. |
attendance:manage |
Recording and amending attendance. |
courses:manage |
Creating courses and assigning students to them. |
grades:manage |
Recording and amending grades and grading schemes. |
schedule:manage |
Timetable resources, entries and class groups. |
timetable:manage |
Building and changing the timetable itself. |
fees:manage |
Fee structures and invoice generation. |
payments:submit |
Declaring a payment against an invoice. |
payments:review |
Accepting or rejecting a declared payment. |
documents:write |
Uploading, renaming, archiving and sharing documents. |
certificates:issue |
Issuing and voiding certificates. |
certificates:signature |
Signing a certificate on the institution's behalf. |
certificates:verify |
Verifying an issued certificate. |
certificates:delegate |
Granting or revoking signature authority. |
notifications:manage |
The institution's message centre. |
resilience:manage |
Recovery posture and the quarterly review. |
deployment:handover |
Evidence that the deployment is ready to be depended on. |
A membership is a state machine, not a flag. Every transition is written to a lifecycle event, so the answer to "why can this person not see that?" is a record rather than a conversation.
| State | Meaning | Recorded event |
|---|---|---|
| Invited | An invitation was issued and has not been accepted. | INVITED |
| Active | The person has access at the assigned role. Only this state grants access. | ACCEPTED |
| Suspended | Access withdrawn without ending the relationship. | DEACTIVATED |
| Archived | The membership is closed. | DEACTIVATED |
| Role changed | The access role was raised or lowered, recorded with both values. | ROLE_CHANGED |
| Restored | A suspended membership is returned to active. | REACTIVATED |
An invitation is addressed to a specific email, carries an expiry, stores only a hash of its token, and is accepted by the invited person. It can be revoked before that happens. Staff number, job title, admission number and tier travel with it, so accepting it creates the right record rather than a blank one.
Not everyone who can manage memberships can promote anyone. Who may assign which role to whom is itself a policy — an administrator cannot create an owner, and an owner cannot be demoted by an administrator. The rule lives on the server beside the capability it qualifies.
A person who belongs to more than one institution keeps one identity and switches between contexts. The active context is resolved per request, so a stale browser tab cannot be used to act in a school the person has since left.
A teacher can be scoped to specific classes rather than the whole institution. Assignments are set, summarised and removed, which is how a school employs a teacher for one subject without handing them the register for the school.
A React client, an Express server speaking tRPC, a typed data layer on MySQL, and managed object storage. Each layer has one job and does not reach into the next one's.
| Layer | Responsibility | Where |
|---|---|---|
| Web client | Role-aware workspaces, accessibility, lazy routes, error recovery, light and dark. | client/src/ |
| Application server | One Node process serving the built client, the protected tRPC API, the sign-in and reset routes, security headers. | server/, api/ |
| Data layer | Typed multi-tenant schema, migrations, repositories, transactional school operations. | drizzle/, server/*Db.ts |
| Identity and access | Sessions, membership resolution, capability policy, invitation acceptance, auditability. |
server/_core/,
server/authorization.ts
|
| Managed files | Object references, signed URLs, sharing and lifecycle for documents. |
server/storage.ts,
server/document*
|
| Operations | Deterministic build, migrations on deploy, backup and restore drill, deployment handover, CI. |
scripts/, deploy/,
.github/workflows/
|
Institutions own campuses, memberships, invitations and their lifecycle events. Enrolment records attach learners to institutions, campuses and tiers. Everything else — attendance, grades, fees, documents, certificates — hangs off those.
That some of them will be curious, and one of them might be hostile. Everything below follows from that rather than from optimism.
Institution and role are never accepted as input. They are derived, per request, from the authenticated session and the membership row behind it. There is no parameter to tamper with because there is no parameter.
Passwords are held as derived hashes with per-account salt, verified in constant time. Reset tokens are stored only as hashes, expire, and are single-use — a second attempt with the same token is refused.
Each session records the password epoch it was issued under. Changing a password moves the epoch forward and invalidates every session issued before it, on every device, without a session table to keep in step.
Every procedure declares the shape it accepts. Values are parsed before they reach a repository, and the data layer uses parameterised queries, so a shape the schema does not describe never travels further than the edge.
Object storage is private. Reads are issued as signed, expiring URLs produced only after the capability and institution have been checked, so possession of a path is not possession of a document.
Credentials and connection strings are environment configuration, never source. The application carries no secret it could leak through a response, a log line or a client bundle.
TypeScript end to end, a schema that is the source of truth for both the database and the API contract, and a small number of moving parts. A school system is not a place for cleverness nobody can debug at term start.
| Concern | Technology | Why it is here |
|---|---|---|
| Interface | React 19, Vite, Tailwind 4 | Fast builds, a component model that scales past fifty screens, and a real design system. |
| Design system | Material Design 3, Radix, shadcn | Accessible primitives underneath a token-based theme, so light and dark are one implementation. |
| Routing | Wouter | A small router with lazy route loading and no ceremony. |
| API | Express 5, tRPC 11, Zod | Typed calls with no hand-written client, and validation that is the same code on both sides. |
| Data | Drizzle ORM, MySQL / TiDB | A typed schema that generates migrations and the query types from one definition. |
| Files | S3-compatible object storage | Documents out of the database, reached only through signed references. |
| Documents | React PDF | Registers, rosters and certificates rendered from the same records the screens use. |
| State and data | TanStack Query | Caching, retries and request lifecycle handled once rather than per screen. |
| Quality | Vitest, TypeScript, Prettier, CI | Tests that run the same way locally and in the pipeline, with a type check gating the deploy. |
| Hosting | Vercel | Production deploys from the repository, functions placed in the region nearest the data. |
A deployment is not finished when the page loads. It is finished when the migrations have run, the restore has been rehearsed, and someone has recorded that it was.
Schema changes are applied as part of the production build, and the deployment is stopped if the configuration or the migration is not valid. A release that would run against the wrong schema does not reach the users.
Recovery is a workspace with a quarterly review and recorded evidence, so the institution can show when it last proved it could come back. The drill is a routine, not a paragraph in a policy.
The deployment handover workspace collects the proof that the
installation is ready to be depended on — configuration, access,
recovery and operations — under
deployment:handover, so readiness is a state
someone can check.
The API runs in the same region as the database, so a query does not cross an ocean to be answered. Region placement is a deployment setting that travels with the project, not a per-environment hope.
Password resets and account notices go out through a dedicated sending domain with SPF, DKIM and DMARC published, so the school's own mail is verifiable and not refused for looking like someone else's.
The type check, the test suite and the format check run in CI. A change that breaks a gate does not deploy, and the gate is the same command that runs locally, so there is nothing to disagree about.
Yes, and that is the point of the tenancy model. Each institution is a tenant with its own campuses, tiers, branding, memberships and records. A person's access is a membership in one institution, and the server resolves which institution a request is acting in before any data is returned.
The isolation is enforced in the data layer, not in the interface. Hiding a navigation link is a convenience; the query filter is the boundary.
Their membership is deactivated rather than deleted. Access ends immediately, the lifecycle event records who did it and when, and everything they recorded stays attached to the institution. Reactivating them later restores the same membership rather than creating a second one.
No. A guardian's access is derived from explicit guardian assignments, and the guardian workspaces are built on those relationships. There is no code path that returns another learner's record to a guardian, so this is a property of the queries rather than a setting someone could get wrong.
Yes. An institution enables the tiers it operates — creche, nursery, primary, secondary, tertiary — and the application adapts to them. Tertiary institutions, for example, can define their own grading scheme rather than being given a default that does not describe how they assess.
The application does not depend on a service the school cannot see or control. One process serves the client and the API; the database and the object storage are the only external dependencies, and both are configuration the operator owns. There is no hidden third-party call in the request path.
Files live in private object storage and are never served from a public path. Opening a document asks the application, which checks the capability and the institution, then issues a signed reference that expires. Shares name their recipient and can be revoked, after which the reference stops resolving.
It is voided, and a corrected one is issued as a new document. Nothing is edited in place and nothing is deleted, so the record of what was issued remains complete — which is the behaviour that survives an inspection.
Yes. The client is responsive throughout, with mobile-specific interaction work — quick actions, drawer gestures and touch targets — and it installs to a home screen as a web app. For a teacher marking a register in a classroom, that is the case that matters.
Material Design 3 places a floor under contrast, focus states and type scale, and the application honours it in both light and dark schemes: visible focus rings, real landmarks and headings, a skip link, and motion that yields to a reduced-motion preference.