User Sign-Up Flows & Role Relationships

Part of: Pickatale Master Build Wiki | Version: v1.8 | Last Updated: 2026-04-18

v1 Scope: Pickatale v1 is school-first only. B2C (parent self-registration, parent-created children, consumer subscriptions) is out of scope for v1. All child accounts originate from the school/teacher flow. Parents are linked observers, not primary account owners.

Who Are The Users?

Pickatale has five user roles. In v1, only the school-led entry path exists.

                        ┌─────────────────────┐
                        │   platform_admin    │  (Pickatale staff — CLI only)
                        └──────────┬──────────┘
                                   │ provisions school
                    ┌──────────────▼──────────────┐
                    │        school_admin         │
                    │   teacher.readingtester.com │
                    └──────────────┬──────────────┘
                                   │ invites teachers
                    ┌──────────────▼──────────────┐
                    │          teacher            │
                    │   teacher.readingtester.com │
                    └──────┬───────────────────────┘
                           │ creates / imports students
                    ┌──────▼──────┐
                    │    child    │  ← canonical learner record (owned by school)
                    │ app.*       │
                    └──────┬──────┘
                           │ parent linked afterward
                    ┌──────▼──────┐
                    │   parent    │  ← secondary linked observer (v1)
                    │ parents.*   │
                    └─────────────┘

The Only Entry Path in v1

There is no B2C path in v1. No parent creates a child. No parent buys access.

Role Summary

Children never self-register. Parents never create child accounts.

The Relationship Model

Ownership Chain (v1 — school-first)

school  (tenant boundary)
  └── school_admin  (manages school, owns school record)
       └── teacher  (member of school, manages classes)
            └── class  (owned by teacher, scoped to school)
                 └── student/child  (canonical learner record, owned by school)
                      └── parent  (linked observer — read-only, scoped by school policy)

Ownership Rules

The school tenant owns the learner record. Parents are linked observers, not owners.

Who Can See What

Account Center — Single Auth Hub for Adults

All adult sign-up, sign-in, and password reset lives at: account.readingtester.com

Children only touch app.readingtester.com.

After login, uc_session cookie is set on .readingtester.com. Each portal reads cookie and routes by role:

Child session cookie: reader_session, scoped to app.readingtester.com only.

Flow A: School Admin Registers (School Bootstrap)

This is the first user in a school. Everything depends on this.

Trigger: School purchases Pickatale or starts a trial.

UI Entry Point: account.readingtester.com/register → "I'm setting up my school"

API Endpoint: POST /api/auth/register

{
  "name": "Sarah Hill",
  "email": "sarah@greenwood.edu",
  "password": "••••••••",
  "role": "school_admin",
  "school_name": "Greenwood Primary School",
  "country": "GB"
}

Backend Actions:

1. Validate (Zod). 422 on failure.
2. Check email uniqueness → 409 if exists.
3. bcrypt hash password (cost 12).
4. INSERT schools (name, country, state='pending').
5. INSERT users (name, email, password_hash, role='school_admin', school_id, state='pending_verification').
6. UPDATE schools.admin_user_id = users.id.
7. INSERT subscriptions (school_id, state='trialing', tier='trial', trial_ends_at=now()+14d).
8. Generate verification token → INSERT email_verification_tokens.
9. Send VERIFY_EMAIL → INSERT email_log, audit_log.

After email verified:

• users.state = 'active', schools.state = 'active'
• Redirect → School Onboarding Wizard (teacher.readingtester.com/setup):
  1. Confirm school details, year groups, curriculum territory
  2. Accept DPA (Data Processing Agreement) — required before any student data stored
  3. Optional: invite teachers
  4. "Go to Dashboard"

Failure Paths:

Flow B: Teacher Invited by School Admin

UI Entry Point: teacher.readingtester.com/settings/team → Invite → enter email(s)

API Endpoint: POST /api/v1/schools/:school_id/invites

{ "email": "james@greenwood.edu", "role": "teacher" }

Backend Actions:

1. Verify requestor is school_admin of this school → 403 if not.
2. Check email uniqueness within school → 409 if duplicate.
3. INSERT invites (school_id, email, role='teacher', token_hash, expires_at=now()+7d, invited_by).
4. Send TEACHER_INVITE email (invite URL: account.readingtester.com/invite?token=).
5. INSERT email_log, audit_log (action='invite_sent').

Teacher accepts (POST /api/auth/invite-accept { token, name, password }):

1. Validate token (exists, not expired, not used).
2. INSERT users (role='teacher', school_id=invite.school_id, state='active') — no email verification needed.
3. INSERT memberships (user_id, school_id, role='teacher').
4. Mark invite used. INSERT audit_log.
5. Set uc_session → redirect to teacher.readingtester.com/dashboard.

Failure Paths:

Flow C: Teacher Self-Registers (No Invite)

Same as Flow A but with role: "teacher" and no school created initially.

After email verification → Teacher Onboarding:

1. "Do you belong to a school?" → Yes / No
2. Yes → search existing schools → if found, send join request to school_admin → teacher waits for approval. If not found → create school (teacher becomes school_admin).
3. No → teacher may register individually (school_id optional). Teacher still holds one teacher_licenses row. Classes and students function identically.

Flow D: Teacher Creates / Imports Students

This is how child accounts are born in v1.

Single student

UI Entry Point: teacher.readingtester.com/class/:id → "Add Student"

API Endpoint: POST /api/v1/classes/:class_id/students

{ "name": "Tommy Anderson", "year_level": 3, "parent_email": "tom.parent@email.com" }

Backend Actions:

1. Verify teacher owns the class → 403 if not.
2. Generate username (firstname + 3-digit suffix, unique). Generate 4-digit PIN.
3. INSERT students (name, username, pin_hash=bcrypt(pin), class_id, teacher_id, school_id, year_level, state='created').
4. INSERT audit_log.
5. Return { username, pin } in response — shown once in modal, not stored in plain text.
6. If parent_email provided: INSERT parent_invite_queue (student_id, parent_email, state='pending') — sent on school policy trigger.

Credentials display: Teacher sees username + PIN once. Print/copy prompt shown. After dismiss: never shown again (only reset available).

Bulk import via CSV

UI Entry Point: "Import Students" → upload CSV

Columns: name, year_level, parent_email (optional)

Backend:

1. Parse CSV → validate each row.
2. Bulk INSERT students (same logic as single, username/PIN generated per row).
3. Return credential sheet (all username + PIN pairs).
4. Print Login Cards button activates → printLoginCards(students, className, 'app.readingtester.com').
5. If parent_email column present → queue parent invites.

Flow E: Child First Login → Placement Test

Trigger: Child enters username + PIN at app.readingtester.com/login.

Backend (child auth):

1. Look up students by username.
2. Check students.locked → 423 if true ("Account locked. Ask your teacher.").
3. bcrypt compare PIN → 401 on mismatch. Increment failed_attempts. Lock after 5.
4. On success: failed_attempts = 0. Set reader_session cookie. INSERT audit_log.

First-time gate: students.placement_test_completed = false → redirect to /placement-test.

Placement test flow:

1. Adaptive passages + comprehension questions (4–8 minutes).
2. On complete: POST /api/placement-result { learner_id, fk_level, raw_scores }.
3. INSERT placement_results. UPDATE students.placement_test_completed = true.
4. Fire to Learner Bot: POST /api/v1/bot/:learner_id/placement-result (X-Internal-Key).
5. Redirect to /library.

Subsequent logins: Skip placement. Direct to /library.

Flow F: Parent Link Flow (v1 — Observer Access Only)

Context: The child account already exists (created by teacher). Parent links to it for read-only visibility.

Who can initiate the parent invite:

• Teacher (from student record in class view)
• School admin (from school-wide student list)
• System (if parent_email was in import CSV — auto-queued, triggered by school policy)

Step 1 — Teacher/school sends parent invite:

UI Entry Point: teacher.readingtester.com/class/:id/students/:student_id → "Invite Parent"

API Endpoint: POST /api/v1/students/:student_id/parent-invite

{ "parent_email": "maria@gmail.com" }

Backend:

1. Verify requestor owns student (teacher_id or school_admin for same school) → 403.
2. Check if parent already linked (students.parent_id not null) — if linked: re-send access link.
3. Generate invite token (UUID v4). INSERT parent_invites (student_id, parent_email, token_hash, expires_at=now()+7d, invited_by=teacher_id).
4. Send PARENT_INVITE email (child name, school name, sign-up/link URL).
5. INSERT email_log, audit_log (action='parent_invite_sent').

Step 2 — Parent accepts invite:

URL: account.readingtester.com/parent-invite?token=UUID

If parent has no account → show registration form (name + password, email pre-filled from invite).

API Endpoint: POST /api/auth/parent-invite-accept

{
  "token": "UUID",
  "name": "Maria Santos",
  "password": "••••••••"   // only if new account
}

Backend:

1. Validate token (exists, not expired, not used).
2. If new account: INSERT users (role='parent', state='active') — email pre-verified via invite.
3. If existing account: verify session matches invite email → 403 if mismatch.
4. UPDATE students.parent_id = users.id.
5. Mark invite used. INSERT audit_log (action='parent_linked').
6. Set uc_session → redirect to parents.readingtester.com/child/:learner_id.

Critical rule: this flow attaches parent to the existing child record. It never creates a new student row.

Step 3 — Parent views tracker:

Parent lands on parents.readingtester.com. Sees only linked children. Read-only.

Failure Paths:

Parent Permissions in v1

Defined decisions (Sig, 2026-04-18):

Parent Decisions — Resolved for v1 [V1-PRODUCTION]

All decisions below are final. Claude Code must implement exactly these rules. Do not invent alternatives.

Flow G: Adult Password Reset

UI Entry Point: account.readingtester.com/forgot-password

API Endpoint: POST /api/auth/forgot-password { "email": "..." }

1. Look up user. If not found → return 200 (prevent enumeration).
2. If found: INSERT password_reset_tokens (expires_at=now()+1h).
3. Send PASSWORD_RESET email. INSERT email_log, audit_log.

Reset (POST /api/auth/reset-password { token, new_password }):

1. Validate token. Validate password strength. bcrypt hash.
2. UPDATE users.password_hash. Mark token used.
3. DELETE all sessions for user. INSERT audit_log.
4. Set new uc_session → dashboard.

Flow H: Child PIN Reset

Children have no email. Only an adult can reset.

In v1, PIN reset is teacher-only by default.

UI Entry Point: teacher.readingtester.com/class/:id/students → student → "Reset PIN"

API Endpoint: POST /api/v1/students/:student_id/reset-pin

Auth: Teacher must own student (same school_id, student in teacher's class) → 403.

Backend:

1. Generate new 4-digit PIN.
2. bcrypt hash. UPDATE students.pin_hash. Reset students.failed_attempts = 0, students.locked = false.
3. INSERT pin_reveal_tokens (plain_pin_encrypted=AES256(pin), expires_at=now()+10m).
4. Return { new_pin: "4782" } — shown ONCE in modal. Not stored in plain text after 10m.
5. INSERT audit_log (action='reset_student_pin').

Parent PIN reset: Not built in v1. Teacher or school_admin can reset child PIN. Parent cannot.

Entitlement in v1 [V1-PRODUCTION]

Entitlement is teacher-licensed. Each teacher holds one subscription covering all their classes. Entitlement resolves from the teacher, not the school.

function checkEntitlement(ctx: { user_id?, school_id?, student_id? }):
  // Called on every feature-gated endpoint — server-side only
  1. Check entitlement_grants WHERE (user_id OR school_id) AND expires_at > now()
     → If found: return { tier: 'full' }
  2. Check teacher_licenses WHERE teacher_id = resolveTeacher(ctx)
       AND state IN ('trialing', 'active', 'past_due' within grace)
     → If found: return { tier: 'full' }
  3. Default: return { tier: 'free' }

Resolving child entitlement: child → class_membership → class → teacher → teacher_licenses.state. The child's entitlement equals the tier of their teacher's license.

Canonical tiers: free, trial, teacher_paid, enterprise, gifted. Tiers parent_paid, school_paid, class_paid do not exist in v1 and must not be built.

Entitlement failure fallback: On Account Center timeout (>2s) → resolve to free. INSERT audit_log (action=entitlement_check_failed). Child can still read 50 free books. Learner Bot paused. Authoritative contract in Page 04, Section 29.3.

Summary: Sign-Up Entry Points (v1)