Documentation

Using Class Margin

Everything a homeschooling parent, a teacher, a teaching assistant or an administrator needs, in the order they need it.

Starting at home

You signed yourself up, so you are the teacher and the administrator and there is nobody to wait for. Five steps, and the first four are the only ones that take a morning.

1. Make the accountSign up with your own email and pick a password. Nothing is invited, approved or assigned — the homeschool is made for you as you go.
2. Add your childrenFirst and last names are enough. A nickname helps if that is what they write at the top of a page. Class numbers and school IDs are for schools; skip them.
3. Photograph a stackOpen the class, choose Grade, and photograph the papers back to back in any order. Do not sort them first and do not write anything on them.
4. Confirm the answers you are asked aboutArithmetic is worked out here rather than trusted, so you are only asked to read the questions that could not be proved. Everything else is already checked.
5. Keep the recordFinalize what you want to keep — finalized work stays past the retention period, which for a homeschool starts at two years. Export a CSV whenever you need one for a portfolio or an evaluation.

Starting at a school

1. Sign inYour school administrator gives you a first password, or you set one yourself from “Forgot your password?” on the sign-in screen. Changing a password signs out anywhere else that was still using the old one.
2. Open your classThe dashboard shows what is waiting: papers to file, students on the roster, papers needing review.
3. Add your rosterNames, class numbers and school IDs. Needed before papers can be matched to students.
4. Invite whoever photographsOften not you. From the class dashboard, add the teaching assistant, aide or volunteer who will hold the phone — they get that one class, and cannot confirm keys or change scoring cards.
5. Grade papersPhotograph papers back to back. No names, no assignment.

Roles

Role	Can do
School admin	School settings, school years, classes, invite staff, assign teachers and assistants to classes, change somebody's role, retention policy, set staff passwords
Teacher	Assigned classes only: roster, assignments, accommodations cards, confirm answer keys, finalize scores, export, and invite a teaching assistant onto their own class
Teaching assistant	Photograph, match unnamed papers, review and override drafts. Cannot edit accommodations, confirm keys, finalize a grade, or invite anybody

Classes and school years

Classes belong to a school year. When a new year starts, an administrator creates it and can copy last year's class names and grades across with empty rosters. Previous years stay readable.

Roster

Each student has a first and last name, an optional nickname, a class number unique within the class, and a school ID unique across the school. All four are used when matching a paper to a student, so a student who writes only "3" at the top can still be found.

Past eight students the roster gains search and sorting. Students with a scoring accommodations card are graded on the list.

Scanning a stack

Open a class and choose Grade.

• Photograph every paper, in any order. Do not sort them first.
• Set pages per paper if a worksheet is more than one page.
• Press send. Papers upload immediately and are read in the background.
• They appear grouped by worksheet. File each group in one go.

Answer keys

The first paper of a new assignment produces a proposed key. Arithmetic in it is checked independently, so you are asked to read only what could not be proved. Correcting an answer re-checks it immediately.

Once confirmed, the key is reused for every later paper. You can review or edit it at any time from the assignment page.

Scoring accommodations

A teacher can give a student a short scoring card: which items count, whether a calculator was expected, whether spelling and handwriting are ignored, and whether shown work earns partial credit. It records scoring rules only, never a diagnosis.

A paper marked with a card applied is always flagged for review, so an accommodation is never applied silently.

Exporting scores

From an assignment, choose Download scores. The CSV carries student number, last and first name, assignment, points earned, points possible, percentage, status and when it was finalized — ready to paste into a gradebook.

What it cannot do

Written down plainly, because finding these out one at a time while grading a stack is worse than reading them once.

Limitation	What happens, and what to do
HEIC photographs	Apple's default photo format cannot be read. The camera button here produces a readable photo; a picture chosen from the camera roll may not. Set Settings → Camera → Formats to Most Compatible.
Poor photographs are not graded at all	Deliberate. If the handwriting could not be read reliably, nothing is scored and you are told to look at the picture. A bad scan must not cost a student points.
Written answers are never scored	Mechanics are counted and a range is suggested with reasons. The score is yours. There is no setting that makes a model decide it.
Only plain arithmetic is verified	“34 + 18 =” is recomputed and proved. Brackets, “½ of 8”, and word problems fall back to how clearly the answer was read, and say so.
An invited assistant still needs a way in	A teacher can add a teaching assistant to their own class, but not give them a password — that stays with an administrator. Where email is configured the assistant sets their own from the sign-in screen; where it is not, an administrator has to. The invite screen says which of the two applies.
Everything by email needs email working	Sign-in links and password resets are sent by the mail provider configured for the site. Until a sending domain is onboarded, delivery is limited to verified addresses, and until then an administrator setting passwords by hand is the way in. The sign-in screen says so rather than sending nothing quietly.
Reading takes about a minute a paper	Photographs upload in under a second and are read in the background, so you keep photographing. A stack of twenty is ready in a few minutes, not instantly.
A name has to be legible somewhere	Name, nickname, class number or school ID. If none can be read the paper waits in Needs attention for you to say whose it is, rather than being guessed at.
Grouping needs readable questions	Papers are grouped by the wording of their questions. A worksheet whose questions did not read is kept on its own rather than filed with the wrong assignment.
Twelve pages per send	Photographs are sent a paper at a time so a dropped connection loses one paper, not the stack. Anything that fails stays on screen to retry.
Reading is done by one model, not a cheap one	Cloudflare's own vision models were measured against a real worksheet and could not read it at all, so pages are read by a model that can. That is what a page costs; there is no cheaper tier that works yet.
No offline capture	Photographs are sent as you go and need a connection. There is no queue that drains later.

Running it yourself

Class Margin runs entirely on Cloudflare: a Worker, D1 for data, R2 for the photographs.

npm install
cp .dev.vars.example .dev.vars
npm run db:migrate:local
npm test
npm run dev

For a deployment you will need a D1 database, an R2 bucket, a session secret, and access to a vision model through an AI gateway. The repository README carries the full list.

Troubleshooting

What you see	What it means
A paper shows 0 of 0	The page could not be read. Use Read photo again, or retake it with the whole sheet in frame.
A paper is unmatched	No name or number was legible. Assign the student by hand; the scores are recalculated.
An assignment shows papers missing	Students on the roster with no paper. An unmatched paper still counts as missing until you say whose it is.
Too many sign-in attempts	Eight wrong passwords locks an address for fifteen minutes.