heliosian/docs/data.md

Data model

The entities the directory serves. Structured data lives in the data source (see docs/plan.md); blobs (photos, audio) are URL references into blob storage.

Person

One record per person, all roles in one shape:

• Key: school email, lowercased. Everyone has one, including the youngest students (their addresses exist but they don't have access yet).
• Names: full name, legal name, preferred name.
• Roles: student, parent, and staff booleans — combinations are valid (staff members are often also parents). Display strings derive from the flags.
• Pronouns: optional; a curated list plus a freeform escape hatch.
• Pronunciation: optional audio recording of the person's name.
• Photo: official portrait or personal upload; people may opt for an illustrated avatar instead.
• Facts: optional about-me text — first-person blurbs for students, professional bios for staff.
• Student fields: grade (Kindergarten, Grade 1 … Grade 8), classroom section, and the parent contact emails for the student.
• Staff fields: job title, department, grade band.
• Contact: email always; phone optional.
• Year rollover: next-year grade and band, so the directory can flip to the new school year.

Family

A family groups adults and kids:

• Key: shared by all members. (Currently a parent's email; minting stable family IDs is a planned migration.)
• Photo and caption: the family photo plus a who's-who description naming everyone in it.
• Pronunciation: optional audio recording of the family name.
• Address: as much as the family chooses to share — full postal address or just city and state.
• Phone: optional family phone.

Classrooms and grades

• Classroom: name, mascot artwork, and the grade band it serves. Some classrooms subdivide into sections (teams); sections have their own logos.
• Section: classroom subdivision with up to a few teachers, a sort order, and named schedule blocks.
• Grade band: pairs of grades share a band with a combined identity — Hummingbirds (K), Halcons (1st/2nd), Jayvens (3rd/4th), Cospreys (5th/6th), Hegrets (7th/8th) — used for browsing, room-parent organization, and band-colored styling (see docs/design.md). A grade → next-grade mapping drives year rollover.
• Room parents: parent assignments per grade band.
• Departments: ordered list organizing the staff view into sections.

Sourcing

Records are imported from the school's systems and enriched by families themselves (photos, facts, pronunciation recordings, address preferences), with each contributed item carrying a last-updated stamp so refresh cadence can be enforced.