Heritage Docs

Appearance

0015 — Homeschool Education Portal ​

Status: Accepted (2026-06-18 — owner accepted during ADR review)

Date: 2026-06-17

ADO work item: AB#3093

Deciders: Kristopher Turner (platform owner)

Context ​

Heritage Virginia hosts an active homeschool cooperative. Families coordinate curriculum, share teaching responsibilities, and — in the high-school years — participate in community-run classes. There is currently no shared system for resource discovery, course scheduling, assignments, or grading; families use ad-hoc tools (email, paper records, third-party apps) that expose child data to outside parties and fragment the community's information.

The platform strategy identifies the Homeschool Education Portal as a distinct Epic (AB#3076) with a Feature (AB#3093) covering two materially different tiers of functionality. These tiers differ in scope, actors, and implementation complexity and must be designed and delivered separately.

The owner clarified this two-tier structure during ADR review:

  • Tier 1 is a lightweight resource and support library for all homeschool families across all ages. It is browse-and-download in nature, carries no grading or assignment logic, and can ship earlier than Tier 2.
  • Tier 2 is a dedicated high-school program with class scheduling, homework assignments, gradebook, and a teacher back-end. It is the LMS-like piece, is a major consumer of the child sub-account model (ADR 0007), and requires deeper design work as the phase approaches. It is called out now but its detailed architecture is explicitly deferred.

Several constraints govern both tiers:

  • COPPA compliance (security audit S1). Students are minors. The platform must not collect child personal information without verifiable parental consent, must not expose child records to unauthorized parties, and must minimize data collected and retained. ADR 0007 handles consent at account-creation time (the minister-approval + parental-consent gate); both tiers must honor that foundation and must not weaken it.
  • Closed community. All participants — students, parents, teachers, and resource browsers — are approved community members. Self-registration by children is prohibited by ADR 0007 and by COPPA.
  • API-first, thin clients (ADR 0008). No business logic, authorization, or data access runs client-side. The portal is a feature slice inside apps/api; surfaces consume it only through api-client.
  • Azure SQL as the relational data store (ADR 0004). Course, assignment, grade, and enrollment records live in the shared Azure SQL database behind the API. No separate LMS database.
  • Server-side RBAC, five canonical roles (ADR 0006). Visibility and write access are enforced by the API. Clients may hint the UI from role claims but are never the authority.
  • Cost constraint. The platform targets free-tier or near-zero operating cost. A third- party LMS with per-seat pricing is incompatible with this constraint.

A decision is required because the feature involves child data, multiple actor types (student, parent, teacher/leader, minister/Admin), and a non-trivial visibility model. The two-tier architecture must be recorded before implementation begins.

Decision ​

We will build the Homeschool Education Portal as two distinct tiers on the platform's API-first core. Tier 1 — the Homeschool Resource & Support Library — is a lightweight browse-and-download feature that can ship earlier and serves all homeschool families. Tier 2 — the High School Program — is the community's in-person class offering with assignments, gradebook, and teacher tools; its detailed design is deferred to the phase in which it is built. Both tiers use existing child sub-accounts (ADR 0007) as the student identity, enforce all data visibility through server-side RBAC (ADR 0006), and store records in Azure SQL (ADR 0004). No third-party LMS will be integrated. Children may not self-register; parental consent recorded at account creation (ADR 0007) is the sole gateway to student participation in any part of this portal.

Tier 1 — Homeschool Resource & Support Library ​

Scope: All member homeschool families; all ages (not restricted to high school). This tier is a library and support hub, not an assignments-and-grades system.

What it contains:

Content typeNotes
Curated and recommended resource linksVetted external links; no child PII crosses to external sites
Unit studies repositoryCommunity-created or community-endorsed unit studies; versioned documents
Community convictions and homeschooling philosophyExplanatory content describing the community's approach and educational values
Downloadable community-specific end-of-year evaluationsForms families use to satisfy state homeschool reporting requirements
Other community forms and documentsAny additional paperwork the cooperative provides to member families

Access model: All member homeschool families have browse and download access, enforced through RBAC (ADR 0006). No grade or assignment records exist in Tier 1. Content is primarily read-only for members; Admin and designated Ministry Leaders (or a future designated role, see Tier 2 note below) can create and update library entries.

Storage: Resource files (unit studies, evaluation forms, PDF documents) are stored via the StorageProvider abstraction defined in ADR 0024, which resolves to Azure Blob Storage under ADR 0004. This is consistent with how the Sermons & Music Hub handles downloadable media (ADR 0010). Metadata (title, category, description, upload date) is indexed in Azure SQL for search and filtering.

Feature slice (apps/api):

apps/api/src/features/homeschool/
  library/       — CRUD for resource links, unit studies, philosophy content, forms
  downloads/     — blob-backed file delivery; signed URL generation via StorageProvider

Delivery timing: Tier 1 is relatively lightweight and can ship in an earlier phase than Tier 2.

Tier 2 — High School Program ​

Scope: High school students enrolled in community-run classes; their parents; assigned teachers; administrators.

What it contains (per class):

ComponentDescription
Homework assignmentsAssignment creation, submission, and return
Class eventsDeadlines, presentations, field trips associated with a class
Class times / class calendarScheduled meeting times integrated with the platform calendar (ADR 0011)

Teacher back-end:

ComponentDescription
Teacher collaboration spaceShared notes and coordination area for teachers of a class or across classes
GradebookGrade entry and history per student per assignment; parent-visible
Teacher notesPer-student notes; parent-visible; student-visible only if explicitly marked so by the teacher

Deferred design — called out now, detailed later. The owner has explicitly noted that Tier 2 requires deeper design work as the phase approaches. This ADR records the intent and the open design considerations below, but does not finalize the Tier 2 implementation architecture. A follow-on ADR amendment or child ADR will close the open questions before Tier 2 enters the build phase.

Open design considerations for Tier 2:

  1. Teacher role / capability. The five canonical RBAC roles (ADR 0006) include Ministry Leader and Small Group Leader. Whether a "teacher" for a community high-school class reuses one of those existing roles or requires a dedicated teaching capability (analogous to the Communications Author question in ADR 0023) is unresolved. Options: (a) map Teacher to Ministry Leader (simplest, may create unintended permission bleed); (b) map Teacher to a new sub-role or capability flag scoped to homeschool courses only. This must be resolved before Tier 2 API design begins.

  2. COPPA and data-protection design. Tier 2 carries the heaviest child-data weight in the portal — grades, teacher notes, and assignment submissions are all covered records. The data-minimization rules, retention policy, and parental-visibility guarantees described below apply, but the detailed endpoint-level enforcement design is part of Tier 2's deeper design work. This is a security HIGH item (audit S1).

  3. Parent-managed student accounts. Tier 2 builds directly on ADR 0007's child sub-account model. All enrollment, grade visibility, and assignment access for a student flows through the parent's account. The enrollment gate must verify that a child sub-account's parent has approved status before the child can be enrolled in any class.

Provisional actor-visibility model for Tier 2:

RoleActor in portalWhat they can see / do
AdminMinister / administratorAll courses, all students, all grades; manage enrollments
Ministry Leader (or teacher capability — see open consideration 1)TeacherTheir assigned courses; students enrolled in those courses; enter and edit grades and notes for their students
Member (parent)ParentTheir own family's child sub-accounts; grades, assignments, and teacher notes (where parent-visible) for their children only
Child sub-accountStudentTheir own assignments and grades; course materials marked student-visible; teacher notes only where explicitly marked student-visible; no other student's records

The API enforces these boundaries on every request. A teacher cannot query another teacher's student records. A student cannot read a peer's grades. A parent cannot read another family's data. These rules are evaluated server-side; no client-side filtering is authoritative.

Provisional feature slice for Tier 2 (apps/api) — subject to deeper design:

apps/api/src/features/homeschool/
  courses/      — CRUD for courses and curriculum units
  assignments/  — assignment creation, submission, and grading
  enrollments/  — student enrollment; parent-consent gate check
  grades/       — grade records; role-filtered read endpoints

Types for both tiers are defined in packages/shared-types/homeschool/ and consumed by both apps/web and apps/mobile. No cross-feature imports; the portal calls platform notification and audit-log services, it does not re-implement them.

Data minimization (COPPA, security audit S1 — applies to both tiers) ​

  • Tier 1 contains no child personal data. Resource files and links are community content, not student records.
  • Tier 2 collects only the data required for course coordination: enrollment, assignment metadata, grade/score, and optional teacher notes.
  • Teacher notes on child records are visible to the child's parent and to Admins; they are not visible to the student unless the teacher explicitly marks them student-visible.
  • No student record is exposed in any public-facing or unauthenticated API surface.
  • Parental consent is on record from ADR 0007's account-creation approval flow; the portal does not re-collect consent but must verify that a child sub-account's parent has approved status before the child can be enrolled in any course.
  • Retention: student records (grades, assignments) follow the platform's data-retention policy, which must be documented in the operational baseline (ADR 0008, responsibility 7) before Tier 2 enters production.

Alternatives considered ​

OptionProsConsWhy not chosen
Two-tier platform feature (chosen)Tier 1 ships early without LMS complexity; Tier 2 deferred for deeper design; no new identity system; COPPA control stays with platform; zero incremental hosting cost; consistent RBACTier 2 requires building course management, assignment tracking, and grading from scratch— chosen
Single combined portal (all features shipped together)One coherent releaseDelays Tier 1 (resource library) behind the heavier LMS build; Tier 2 is not ready for full design yet; mixing lightweight and heavy features in one phase creates scope-creep riskRejected — the two tiers differ enough in complexity and readiness that bundling them together is a delivery risk
Integrate a third-party LMS (Google Classroom, Canvas, etc.)Mature feature set; low initial build costChild PII sent to third-party servers (COPPA violation — parental consent was granted to this platform, not to Google/Instructure); breaks closed-community guarantee; breaks server-side RBAC; per-seat cost; single-sign-on complexityRejected — COPPA control, closed-community, RBAC, and cost constraints all fail
Allow children to self-register for coursesSimpler enrollment UXViolates COPPA (no parental consent gate); violates ADR 0007 closed-community/approval model; children cannot create their own sub-accountsRejected — prohibited by ADR 0007 and COPPA
Separate student identity system (distinct from ADR 0007 child sub-accounts)Could be tailored to LMS workflowsDuplicates the user table, the family-group model, and the approval workflow defined in ADR 0007; two sources of truth for child identity; double the COPPA surface areaRejected — ADR 0007 is the single identity system; the portal is a consumer, not a new identity layer
Use a third-party file host (Google Drive, Dropbox) for Tier 1 resourcesNo build effort for file storageChild-adjacent community content on third-party servers; breaks the closed-community model; no RBAC; inconsistent with the platform storage strategy (ADR 0024)Rejected — inconsistent with StorageProvider abstraction and closed-community guarantee

Consequences ​

Positive ​

  • Tier 1 can ship in an earlier phase without waiting for Tier 2 LMS design, giving homeschool families immediate value (resource library, forms, philosophy documentation).
  • Student identity, parental consent, and the family-group relationship are already handled by ADR 0007; both tiers inherit them at no additional architectural cost.
  • COPPA compliance remains in one place (the platform's account-creation approval flow + server-side RBAC enforcement); the portal does not create a new regulatory surface.
  • Zero incremental hosting cost: resource files go to the existing Blob Storage account via the StorageProvider abstraction (ADR 0024); relational records go to the existing Azure SQL instance (ADR 0004); compute stays in the existing Azure Functions API (ADR 0008).
  • Separating the tiers makes scope and risk explicit. Tier 2's open design questions (teacher role, data-retention policy, COPPA endpoint design) are flagged as required prerequisites rather than discovered mid-build.
  • Tier 1 resource files use the same StorageProvider pattern established for Sermons & Music Hub (ADR 0010, ADR 0024), keeping file delivery consistent across the platform.

Negative / trade-offs ​

  • Tier 2 (gradebook, assignments, teacher tools) must be built from scratch. The trade-off is accepted because third-party LMS options fail the COPPA, closed-community, and cost constraints.
  • The teacher role / capability question (open consideration 1 above) must be resolved before Tier 2 API design begins. If a dedicated teaching capability is needed, it extends the RBAC model defined in ADR 0006 and must be recorded in a follow-on amendment.
  • The portal depends on the platform shipping first (ADR 0008 phase gate). Tier 1 is lighter and can follow the platform core closely; Tier 2 cannot be built or tested independently.
  • Teacher-note visibility rules (parent-visible vs. student-visible) add branching logic to grade-read endpoints in Tier 2; this must be covered by integration tests before go-live.

Risks ​

  • COPPA data-retention gap. The platform does not yet have a documented retention and deletion policy for child records. This must be closed in the operational baseline (ADR 0008, responsibility 7) before Tier 2 enters production. Mitigation: block Tier 2 production deployment with a documented policy; track as a prerequisite work item. Tier 1 is not blocked (no child personal data).
  • Enrollment gate bypass (Tier 2). If the API does not verify parental-consent status before enrolling a child sub-account, a child could be enrolled without active parental approval. Mitigation: the enrollment endpoint must call the ADR 0007 approval-status check; this is a required integration test case.
  • Role boundary erosion (Tier 2). A teacher could inadvertently receive access to students outside their courses if enrollment queries are not scoped correctly. Mitigation: all student-record endpoints filter by enrollment rows that explicitly link a student to a teacher's course; no implicit "see all students" grant exists for any non-Admin role.
  • Scope creep toward a full LMS (Tier 2). The portal is intended for a small homeschool cooperative, not a district-scale platform. Mitigation: limit Tier 2 scope to courses, enrollments, assignments, grades, and the teacher collaboration space; defer advanced features (auto-grading, rubrics, learning-path branching) to later iterations if demand is demonstrated.
  • Tier 1 resource quality control. A library of external links and downloadable documents requires ongoing curation. Stale or broken links reduce trust. Mitigation: Admin and designated content managers are responsible for curation; the API should record last-verified dates on resource links so staleness is visible.

References ​

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner