Yearbook.systemsBook a walkthrough

Yearbook.systems · the operational control tower

Run 40 kids against 400 dated pages without losing track of who touched what.

This is not the book a family reads, and it is not what the newsroom feels like. It is the console an adviser runs the whole program from: who is on staff and what they may do, which student may edit which block of which spread, the plan that turns a page count into an ordered flatplan, the states every spread walks to the printer, and the one live list of what needs the adviser today.

Book a walkthrough See how it holds control
You want to READ the book

The finished book a family opens lives at onlineyearbook.software. That is the product; this is the operations behind it.

You want the ROOM

What staff culture, deadlines-night and the newsroom feel like lives at yearbook.zone. This page is the machinery, not the mood.

5staff roles in the closed vocabulary — and exactly one of them is finance-capable
5ordered production states every spread walks, from empty to final
6live signals on the adviser worklist, each a real count from a shipped read
2stable deny codes on the write-grant cage — both fail closed, never open

Staff & roles · separation of duties

Five roles. One approver. Zero students anywhere near the money.

The roles an adviser can assign are a closed vocabulary — a role not on this list cannot be given. Two capability flags matter for governance: who can approve and lock pages, and who is finance-capable. Only the adviser carries either. The four student-holdable roles carry neither, and that is not a default someone can change.

Role tokenWhat it isCan approve / lockFinance-capable
chief_editorChief Editor
Full editorial control across the book -- but not an approver and not finance-capable.
nono
staff_editorStaff Editor
Edits the pages and spreads assigned to them.
nono
restricted_staffRestricted Staff
Only the pages explicitly assigned to them -- nothing else in the book.
nono
photographerPhotographer
Uploads photos to the folders and albums assigned to them.
nono
adviserAdviser
Approves and locks pages; manages money and deadlines. The one approver in the room.
yesyes

The non-negotiable rule, enforced in code. A validator refuses to assign any finance-capable role to a member marked as a student, returning a plain issue instead of silently allowing it. Minors edit the book; they never touch money or the finance side of the program. The other finance-capable identity is the platform-level district_admin — an administrator, never a student.

Assignment & scope · who can touch what

A student writes only their blocks — and the cage fails closed.

Assignment is enforced per block of a spread, not per page and not on the honor system. A scoped student’s reach is the union of their persisted write grants. An edit is allowed only when every block it touches is inside that union; a single off-region block denies the whole operation, because a collaborative update is one transaction and cannot be partially applied. A scoped student with no grants at all cannot structurally write.

The per-block write-grant containment cageA spread is a grid of blocks. A scoped student may write only the blocks granted to them; an edit touching any un-granted block is denied whole, and a student with zero grants is denied fail-closed. Advisers, co-advisers, admins and the Editor-in-Chief bypass the cage.One spread — the blocks a scoped student may writeblock 1grantedblock 2grantedblock 3off-regionblock 4grantedblock 5off-regionblock 6off-regionEdit touches block 1 + block 5DENY assigned:off-region:block-5 — the whole op is refused (one transaction, no partial apply)
The containment cage An edit touching block 1 (granted) and block 5 (off-region) is refused whole with a stable deny code. All-must-pass: the first off-region block ends the op.
assigned:scope-unresolved
A scoped student with ZERO grants on the spread. A student with no assignment may not structurally write -- the gate fails closed rather than defaulting open.
assigned:off-region:<blockId>
A touched block sits outside the union of the actor's grants. The FIRST off-region block denies the WHOLE op -- a Yjs update is one transaction and cannot be partially applied.

Who bypasses the cage. The people who SET the assignments are never region-bound: adviser co_adviser district_admin school_admin support_admin partner_admin editor_in_chief. Everyone else is caged to exactly their grants. The predicate is pure and unit-tested, and it returns the same deny codes the live collaboration gate already speaks, so the resolver and the gate can never disagree on “is this an adviser.”

The ladder / flatplan · the production plan

A page count and a section list become an ordered, role-stamped book.

You describe the book: an interior page count and an ordered list of content sections, each with a compose role and an optional page budget. The flatplan driver lays the canonical spine — cover, endsheet, title, your content, then index, colophon and autographs — and stamps every spread with the engine that fills it. It is deterministic: the same plan produces the same flatplan every time, so a re-run reproduces the identical book and a test pins it exactly.

The section-typed flatplan, front to backThe book spine in walk order: cover and endsheet leaves, a title spread, content and people and feature spreads, then index, colophon (reserved, honest-off), autographs, and the back leaves. Each spread is stamped with the compose role the conductor dispatches on.A book plan becomes an ordered, role-stamped flatplanCovercoverEndsheetendsheetTitletitleStudent LifecontentSportscontentPeoplepeopleFeaturefeatureIndexindexColophoncolophonAutographsautographEndsheetendsheetCovercoverPage budgets split by the same largest-remainder math the editor’s ladder view uses — deterministic, same plan in, same book out.
The section-typed flatplan The spine in walk order. People spreads dispatch to the portrait engine, content to the candid engine, features to the rich-template path. Colophon is reserved but honest-off.
Compose roleEngine dispatchedWhat it doesKind
peopleportraitFlowThe portrait section -- a deterministic roster paginator.auto-composed
contentdraftSpreadThe candid/coverage workhorse -- autoLayout from the consent-gated pool.auto-composed
featureapplyRichTemplate + draftSpreadA designed feature spread; copy threaded by computeFlowPlan when budgeted.auto-composed
indexbuildIndexThe back-of-book name/topic index, alphabetized from placement data.auto-composed
dividerstructuralOne styled spread that opens a content run (consumes a section spread).structural
titlestructuralFront-matter title spread, body pp.1-2. Typed, not auto-packed.structural
colophoncolophonSealBlock (honest-off)The plan RESERVES the spread; the seal block is not wired into the worker boot yet.structural
autographstructuralBlank signature pages -- an empty styled spread, no engine.structural
cover / endsheetstructuralNon-folio leaves; outside the body page count, not auto-composed.structural

Where the line is drawn, honestly. This driver PLANS; a separate conductor service walks the plan and calls each shipped engine to compose the spread. The plan can reserve a colophon spread, but the colophon seal block is not yet wired into the worker boot — so the page says “reserved,” not “printed.” Nothing here designs your book with a model; the layout math is deterministic and inspectable.

Production & proofing · the state machine

Every spread walks one ordered path, and the adviser holds the lock.

A spread advances through five ordered states. Because the states are ordered, progress is just position on the path — which is what lets the control tower always surface the pages furthest from done. “Proofed” is a real gate: a second set of eyes on names, dates and spelling. “Final” means approved and locked for the printer, and only the adviser can approve and lock.

The production status workflowA spread advances through five ordered states: empty, started, design-done, proofed, final. Proofed means a second reader checked it; final means it is approved and locked for the printer.Every spread walks one ordered path to the printerempty0%→started25%→design-done50%→proofed75%→final100%The ordering IS the progress math — the worklist can always surface the pages furthest from done.
The production status workflow empty → started → design-done → proofed → final. The percentage under each state is its progress weight; the worklist reads them to find what is slipping.
empty
Empty
The spread exists on the plan; nobody has started it.
started
Started
Someone is building it -- photos and copy are going in.
design-done
Design done
The layout is finished and ready for a second set of eyes.
proofed
Proofed
A second reader has checked it -- names, dates, spelling.
final
Final
Approved and LOCKED for the printer. No further edits.

Print-plant deadlines are first-class. The adviser sets internal deadlines against sections and spreads; a spread whose deadline has passed and is not yet approved surfaces on the worklist and deep-links to planning. At plan time the flatplan also warns when a page count is odd (rounded up — books print in even leaves) or not divisible by four (printers impose in four-page signatures), so the plan already matches how the plant binds the book.

The control tower · “Needs you”

One live list of what actually needs the adviser today.

Six signals, each a real count from a surface the adviser already runs. A row with a zero count is dropped, so the list is the live work and never a parade of zeroes. Each read resolves independently and fails soft — a read that is unavailable contributes nothing rather than blanking the page or inventing a number.

openPhotoFlags
Roster photo flags to resolve
Portraits a subject flagged for a retake or fix.
deep-links → /roster
pendingNameCorrections
Name corrections to approve
Spelling fixes awaiting adviser approval before print.
deep-links → /roster
retakePending
Portrait retakes pending
Subjects waiting on a re-shoot.
deep-links → /roster
unproofedSubjects
Roster rows not yet proofed
Names and portraits still awaiting subject verification.
deep-links → /roster
suppressedStudents
Students suppressed from the book
Do-not-publish or publication-denied subjects excluded.
deep-links → /roster
overdueSpreads
Spreads past their deadline
Pages whose internal deadline has passed and aren't approved yet.
deep-links → /planning

Why this matters. The workspace used to hard-wire every count to zero, so it was structurally always “all caught up” — a lie by omission on the one triage surface an adviser trusts. Now “all caught up” appears only when every read genuinely returns zero. The cockpit tells the truth or it stays quiet.

In proportion · not a bare number

The honest fractions behind the console.

Stated plainly · what this page does not claim

The parts that aren’t wired, named out loud.

[ ]

The colophon seal block is not wired into the worker boot. The flatplan can reserve the colophon spread; it is not composed yet.

[ ]

Region-scoped write grants resolve from a persisted per-block map. A book with no grants leaves a scoped student at the fail-closed floor — that is by design, not a claim that every book already carries grants.

[ ]

No face-matching, no facial recognition, no AI photo-tagging anywhere on this surface. The flatplan is deterministic layout math, not a model guessing your design.

[ ]

No mail is sent, no inbox is provisioned, and there is no reply-from address on this product. This page provisions no mailbox.

[ ]

No checkout, no card capture, no charge on this site. Money capability in the program is adviser-only by construction; commerce is a separate product and is not switched on here.

Questions an adviser and a district technologist actually ask

Straight answers, traced to the mechanism.

How is this different from onlineyearbook.software or yearbook.zone?
They answer different questions. onlineyearbook.software is where a FAMILY reads the finished book -- the product a reader holds. yearbook.zone is what staff CULTURE feels like -- the room. yearbook.systems is neither: it is the CONTROL TOWER an adviser runs the program from. Staff structure, spread-by-spread assignment, the production ladder, print deadlines, proofing and approval. If you want to read a book, or feel the newsroom, those are the pages for you.
Can a student ever touch the money side of the program?
No, and it is not a policy toggle -- it is refused in code. Of the five assignable staff roles (chief_editor, staff_editor, restricted_staff, photographer, adviser) only adviser is finance-capable. A validator (validateRoleAssignment) blocks assigning ANY finance-capable role to a member marked as a student, returning a plain issue rather than silently allowing it. Separation of duties is the point: minors edit the book; they never see the money.
What actually stops a staffer from editing a spread that isn't theirs?
A per-block write-grant containment predicate. A student's scope is the UNION of their persisted grants on that spread. An edit is allowed only if EVERY block it touches is inside that union; the first off-region block denies the whole operation, because a collaborative update is one transaction and cannot be partially applied. A scoped student with zero grants is denied fail-closed (assigned:scope-unresolved); an off-region block returns assigned:off-region. Advisers, co-advisers, admins and the Editor-in-Chief bypass the cage entirely -- they set the assignments, so they are never region-bound.
Does the platform lay the book out for me automatically? Is that AI?
It PLANS the book deterministically; it does not invent a design with AI. You describe a book plan -- a page count and an ordered list of sections, each with a compose role and an optional page budget -- and the flatplan driver turns it into a section-typed flatplan: an ordered list of spreads, each stamped with the shipped engine that fills it. Same plan in, same flatplan out, every time -- so a re-run reproduces the identical book and a test pins it exactly. A separate conductor service then walks the plan and calls each engine (portrait flow for people, the candid engine for content). No model guesses your layout.
How are the section page budgets divided?
By the same largest-remainder (Hamilton) split the editor's ladder view uses -- byte-for-byte, so the plan the server builds lays the book out identically to what an editor sees on screen. Each section is weighted by its target page budget, every section is guaranteed at least one spread when there is room, and the rounding remainder is distributed largest-fraction-first with ties broken by order. It is deterministic, so two people planning the same book get the same book.
What are the production states a spread moves through?
Five, in order: empty, started, design-done, proofed, final. 'Proofed' means a second set of eyes has checked names, dates and spelling; 'final' means the spread is approved and LOCKED for the printer. The ordering is the whole point -- progress math and the 'least-done first' worklist fall straight out of it, so the cockpit can always show you the pages furthest from done.
What does the adviser 'Needs you' list actually show?
Six live signals, each a real count from a shipped read: open roster photo flags, name corrections awaiting approval, portrait retakes pending, roster rows not yet proofed, students suppressed from the book, and spreads past their internal deadline. A row with a zero count is dropped, so the list is the live work -- never a wall of zeroes. Each read is resolved independently and fails soft: a read that is unavailable contributes nothing rather than blanking the page or inventing a number. When every read genuinely returns zero, 'all caught up' is TRUE, not a placeholder.
How do print-plant deadlines fit in?
The adviser sets internal deadlines against sections and spreads; a spread whose deadline has passed and is not yet approved surfaces on the worklist as 'past its deadline' and deep-links to planning. The flatplan also warns, at plan time, when a book's page count is odd (rounded up -- books print in even leaves) or not divisible by four (most printers impose in four-page signatures) so the plan matches how the plant actually binds the book, before anyone designs a page.
What happens to a student who opted out of the book?
A do-not-publish or publication-denied subject is excluded from the book and only COUNTED on the adviser worklist so the adviser knows how many seats the suppression wall is removing. Minor data is consent-aware, access-controlled, and never made public. Suppression is a wall, not a filter a client request can lift.
Is there a live checkout or payment on this page?
No. There is no card capture, no charge, and no checkout anywhere on this site. Money capability in the program is adviser-only by construction (see the roles question above); the commerce surface is a separate product and is not switched on here. This page is the operations manual, not a store.
What is honest-off today, stated plainly?
The colophon seal block is not yet wired into the worker boot -- the flatplan can RESERVE the colophon spread, but the seal is not composed. Region-scoped write grants resolve from a persisted per-block map; a book with no grants leaves a scoped student at the fail-closed floor. And nothing on this page does face-matching, AI photo-tagging, mail delivery, or payment. Where a capability isn't wired, the page says so instead of implying it runs.

Book a walkthrough

See your program in the console — no signup, no card.

We walk the real surfaces honestly: the role matrix, the write-grant cage, the flatplan driver, the production ladder, and the live worklist. Where something is honest-off, we show you exactly where the line is.

[email protected]