HiBFF Schools — The Complete Programme Document

Audience: School leadership, district administrators, mayors, civic partners, parents, and the HiBFF internal team. Owner: Robert Parson, Founder & CEO, HiBFF Status: Live — Production Last revised: February 2026 Related documents:

HIBFF_PARENT_TEEN_CHARTER.md

,

HiBFF_Schools_Market_Report.pdf

,

PRODUCT_SCHOOL.md

Table of contents

1. What HiBFF Schools is
2. Why it exists
3. The three commercial tiers
4. The Dynamic Challenge Engine
5. Conversational onboarding & OCEAN profiling
6. Hybrid Custodial Vault & NFT progression
7. Aggregate-only data architecture
8. The Schools Command Centre (admin UX)
9. HiBFF Gives — civic-led free programme
10. Mayor outreach & CRM pipeline
11. Postmark mail-merge & follow-up engine
12. Safeguarding, COPPA, FERPA & dual-consent gating
13. Onboarding a school in 14 days
14. Success metrics & internal SLAs
15. Frequently asked questions
16. Glossary

1. What HiBFF Schools is

HiBFF Schools is the school-deployment surface of the HiBFF platform — a teen-empowering "practice gym" for real-world social skills. It pairs every student with a safe AI partner (an AvA), gives them a personalised 20-challenge social-skills journey, and delivers strictly aggregate-level analytics to school staff. No staff member ever sees an individual teen's conversation. That is the central design promise.

In one sentence: "Every teen gets a private practice space; every school gets the data it needs to support without surveilling."

2. Why it exists

Three converging problems:

1. The pastoral gap — Schools are now expected to deliver social-emotional learning at scale, but counsellor-to-student ratios in the US average 1:430 (ASCA, 2024). Most teens never speak to one.
2. The privacy paradox — Existing "wellbeing apps" inside schools either spy on teens (which destroys trust) or stay so silent that staff have no early warning of distress.
3. The confidence cliff — UK & US data both show a measurable drop in real-world conversational confidence in 13-17 year-olds since 2019. Practice space, not surveillance, is what closes this.

HiBFF was built to occupy the missing middle: teen-private, school-visible-in-aggregate.

3. The three commercial tiers

The 60-city HiBFF Schools target list (see

HiBFF_Schools_Market_Report.pdf

priority_label

The same backend table (

outreach_targets

not_contacted → letter_sent → enquiry_received → in_discussion → active → declined

4. The Dynamic Challenge Engine

The Schools Programme is built around the Dynamic Challenge Engine — a 70-variant library that produces a cohort-unique 20-challenge journey for every teen.

4.1 The library

• 70 variants, organised as:
  • 10 Tier-1 themes × 3 variants each = 30 cards (foundation: hello, listening, asking, etc.)
  • 9 Tier-2 themes × 4 variants each = 36 cards (depth: conflict, generosity, leadership, etc.)
  • 1 canonical Tier-2 finale = 4 cards ("The Secret Kindness")
• Each variant has:

  theme_key

  ,

  tier

  ,

  variant

  ,

  core_action

  ,

  full_text

  ,

  ava_intro

  ,

  content_status

  (

  draft

  /

  review

  /

  live

  ).
• Stored in

  db.challenge_library

  with compound indexes on

  (tier, theme_key, variant)

  .

4.2 Per-teen journey assembly

• On onboarding completion,

  assign_journey()

  builds a unique 20-challenge sequence:
  • 10 Tier-1 cards (1 per theme; variant chosen by teen's extraversion band)
  • 9 Tier-2 cards (variant chosen by per-theme growth-edge)
  • 1 finale ("Secret Kindness" canonical T2-10)
• A 5-retry uniqueness loop guarantees the journey doesn't collide with any other active teen in the same cohort. If retries exhaust, a best-permutation fallback is taken and a warning is written to

  engine_warnings

  .
• Stored in

  db.teen_challenges

  keyed by

  (teen_id, challenge_id)

  .

4.3 Per-card lifecycle

Each challenge card moves through events captured in

db.challenge_flow_events

assigned → viewed → attempted → completed   (or → skipped)

Completion runs three checks:

1. Specificity — reflection text length / topic adherence.
2. Sincerity heuristic — short-form NLP signal in completion prose.
3. Goodwill heuristic — flagged when prose mentions a third party positively.

If sincerity ≥ 0.6, a rare "Sincerity" NFT is minted. If goodwill ≥ 0.6, a rare "Goodwill" NFT. Otherwise an achievement NFT is minted via the Hybrid Custodial Vault (§6). NFT mint failures are non-fatal — the challenge always completes locally.

4.4 Sankey flow analytics

GET /api/admin/schools/sankey

challenge_flow_events

{nodes, links}

@nivo

#F5831F

#7B4FD8

5. Conversational onboarding & OCEAN profiling

The classic "OCEAN" Big-Five personality questionnaire has been re-engineered as a conversational flow led by the AvA character (Maya by default, configurable per school).

• 26-step script: 8 lightweight preference questions + 15 OCEAN scenario questions (3 per trait) + 3 framing turns.
• Native browser TTS + speech recognition —

  speechSynthesis

  and

  webkitSpeechRecognition

  only. No third-party STT/TTS dependency. Works offline once the page is loaded.
• Idle-loop video of the AvA character runs at 681 KB on the registration page (

  /api/ava-video/registration-greeter

  ). The character looks like she's listening even when the teen says nothing.
• OCEAN scoring runs server-side on submit (

  POST /api/schools/onboarding/submit

  ). Scores are stored in

  db.teen_profile_preferences

  .
• The 8 lightweight prefs (favourite colour, hobby, season, animal, food, etc. + "one-word goal") are reused later as conversational prompts inside AvA chat — making the AvA feel like she remembers the teen.

5.1 Why a conversation, not a quiz

A 50-item Likert scale would take 11 minutes and feel clinical. The conversational flow takes 4-6 minutes, surfaces the same OCEAN signal, and produces a 30-40% higher onboarding completion rate in pilot data.

6. Hybrid Custodial Vault & NFT progression

Every completed challenge mints an NFT into a Hybrid Custodial Vault held in the teen's name. This isn't a crypto product — it's a tamper-proof transcript of social growth.

• Minting: via Crossmint API on Polygon EVM (test) / mainnet (prod).
• Custody: HiBFF holds the wallet for the teen until they turn 18, then keys are released in a guided handover.
• Per-NFT 180-day timelock — a teen cannot transfer or burn an NFT for 180 days from its mint date. (Previously per-account, now correctly per-NFT.)
• Double-mint guard — a compound unique sparse index

  collectibles_user_quest_unique

  on

  (user_id, quest_id)

  ensures no challenge can be minted twice, even under concurrent races.
• Age gating — teens under 13 do not see the on-chain wallet at all; they see a styled "achievement card" instead. Backend behaviour is identical.

The 23 ★★★ Gives priority cities all start at the Free subscription tier; their NFT supply is funded from the HiBFF Gives donations pool.

7. Aggregate-only data architecture

The single most-tested rule in the codebase:

No school-side endpoint may return individual teen identifiers.

This is enforced at three layers:

1. API layer — all

   /api/admin/schools/*

   endpoints route through

   require_role(ADMIN, SUB_ADMIN)

   and the response shape is whitelisted (

   school_id

   ,

   school_name

   ,

   active_teens

   ,

   teens_with_journey

   ,

   challenges_completed

   ,

   avg_completed_per_teen

   ,

   by_theme

   ,

   by_status

   ). No

   teen_id

   , no

   email

   , no

   name

   .
2. Aggregation layer —

   db.teen_challenges.aggregate

   always groups by

   theme_key

   or

   status

   , never by teen.
3. Test layer —

   tests/test_schools_engine.py

   includes a contract test that scans the JSON of every admin endpoint for forbidden field names and fails the build if any leak.

When parents need teen-level data, they get it through the Parent Dashboard (a separate surface, governed by the Parent + Teen Charter — see

HIBFF_PARENT_TEEN_CHARTER.md

8. The Schools Command Centre (admin UX)

Lives at

/admin/schools-engine

8.1 Tabs

full_text

ava_intro

draft → review → live

8.2 Outreach Tracker controls (top bar)

• Follow-up queue — surfaces letter_sent rows idle ≥ 7 days with no reply (§11).
• Activity feed — live Postmark webhook stream (delivery, open, click, bounce, mayor reply).
• Market report — embedded PDF viewer of the latest market intelligence document with admin notes textarea.
• Re-seed from spreadsheet — re-imports the 60-city master Excel file. Idempotent — admin-edited CRM fields are preserved.

9. HiBFF Gives — civic-led free programme

HiBFF Gives is the philanthropic arm. Mayors of underserved US cities donate the programme to every K-12 school in their town for $1/year — symbolic — and HiBFF takes a 45% local profit-share once the city's paying parent subscribers cross break-even.

9.1 Eligibility (★★★ tier)

• US city, population 100k–300k (with strategic exceptions).
• Median household income < $50k OR poverty rate ≥ 18%.
• Mayor or schools superintendent confirmed reachable on LinkedIn.
• Mayor invitation accepted (digital signature).

9.2 What the city gets

• Full HiBFF Schools programme — free for every K-12 school in the jurisdiction.
• Mayor Portal (

  /portal/mayor

  ) with aggregated, town-wide KPIs.
• Annual HiBFF Gives Report — public PDF of the year's outcomes.
• Public placement on the HiBFF Gives leaderboard at

  /gives

  once activated.

9.3 Mayor Portal scope

• Engagement KPIs at city level: active teens, schools live, teens completing 20-challenge journey, OCEAN improvement.
• Sankey-equivalent at city level (planned Q3 2026).
• Wraps the public site shell (header, footer, brand) — never feels like a separate microsite.
• Magic-link authentication via Postmark — no password.

10. Mayor outreach & CRM pipeline

The Outreach Tracker turns the static 60-city spreadsheet into a live CRM.

10.1 Data origin

• Source file:

  HiBFF_Schools_Outreach_AllRegions.xlsx

  (4 tabs, 60 rows).
• Bundled at

  /app/backend/app/data/

  .
• Auto-seeded on every backend startup via

  app.services.outreach_seed.seed_outreach_targets()

  .
• Idempotent: the only field overwritten on reseed is the demographic data (population, income, poverty, mayor name). Admin-edited CRM fields (

  status

  ,

  outreach_email

  ,

  letter_sent_date

  ,

  next_action

  ,

  gift_value_usd

  ,

  crm_notes

  ,

  linkedin_url

  ,

  response_date

  ,

  next_action_due

  ) are preserved.

10.2 Pipeline stages

not_contacted     ← seeded default
↓
letter_sent       ← admin-clicked Send, OR Postmark Delivery received
↓
enquiry_received  ← Postmark Inbound webhook OR manual edit
↓
in_discussion     ← admin moves manually (call scheduled)
↓
active            ← contract signed; auto-mirrors to gives_communities (planned Q3 2026)
[declined]        ← admin choice OR Postmark HardBounce / SpamComplaint

in_discussion

active

declined

10.3 KPI strip (always visible)

Total cities · Letters sent · Enquiries in · In discussion · Active · Pipeline value $.

The pipeline value sums

gift_value_usd

letter_sent / enquiry_received / in_discussion / active

10.4 Filters

Region (5 chips: All / E North Central / W North Central / South / West) · Priority (★★★ / ★★ / ★) · Status (any pipeline stage).

11. Postmark mail-merge & follow-up engine

11.1 Outbound — initial invitation

• Endpoint:

  POST /api/admin/outreach/targets/{id}/send-letter

  .
• Three flavour templates rendered server-side from

  priority_label

  :
  • Gives (★★★) — civic, free programme framing.
  • Outreach (★★) — schools partnership framing.
  • Paying (★) — quiet parent-facing framing.
• All three auto-inject city, mayor name, state, and the per-row spreadsheet notes (e.g. "Notre Dame proximity, high youth need").
• Editable before send: the SendLetterModal lets the admin override subject and HTML body before dispatch. Default content is pre-filled.
• On success: Postmark message ID + recipient logged to

  db.outreach_letters_sent

  ; pipeline auto-advances to

  letter_sent

  with today's date.

11.2 Outbound — follow-up

• Trigger criteria: row in

  letter_sent

  for ≥ 7 days,

  response_date

  empty, no follow-up sent in the past 7 days.
• Surfacing: "Follow-up queue" button at the top of the Outreach Tracker shows a sorted list (most-idle first).
• Same edit-before-send UX as the initial invitation — the

  SendLetterModal

  is reused with

  kind="followup"

  .
• Two-variant tone depending on whether Postmark recorded a

  first_opened_at

  :
  • Open recorded → "I noticed my note found its way to your inbox, so I thought I'd circle back…"
  • No open → "I wrote a couple of weeks ago about HiBFF and didn't want to assume my note got buried…"
• Endpoint:

  POST /api/admin/outreach/targets/{id}/send-followup

  .
• Sets

  last_followup_at

  + increments

  followup_count

  on the target.

11.3 Inbound — webhook ingestion

• Endpoint:

  POST /api/public/outreach/postmark-webhook?token=…

• Auth: shared secret in URL query, compared against

  POSTMARK_WEBHOOK_SECRET

  in

  .env

  .
• Match strategy:
  1. Postmark

     MessageID

     →

     outreach_letters_sent.postmark_message_id

     .
  2. Fallback:

     Email

     /

     From

     /

     Recipient

     →

     outreach_targets.outreach_email

     .
• Behaviour by RecordType:

Delivery

first_opened_at

Open

first_opened_at

Click

Bounce / HardBounce

declined

Bounce / SoftBounce

SpamComplaint

declined

InboundEmail

enquiry_received

Every event is logged to

db.outreach_events

11.4 Postmark configuration

Set the webhook URL in the Postmark dashboard (Servers → outbound → Webhooks):

https://hibff.com/api/public/outreach/postmark-webhook?token={POSTMARK_WEBHOOK_SECRET}

Tick: Delivery, Open, Bounce, Spam Complaint plus the Inbound stream MX route.

12. Safeguarding, COPPA, FERPA & dual-consent gating

12.1 Dual-consent charter

Before a teen can use the Dynamic Challenge Engine inside a school deployment, both:

1. Parent must sign the Parent Compact (digital signature in the Parent Dashboard).
2. Teen must sign the Teen Digital Compact (digital signature in the teen onboarding flow).

If either signature is missing,

POST /api/schools/journey/complete

code: charter_not_active

/api/family/consent-banner

HIBFF_PARENT_TEEN_CHARTER.md

12.2 COPPA (US)

• Teens 13-17 supply a parent email at registration.
• The parent receives an invitation email (Postmark,

  parent-invite

  tag).
• Parent must verify the link, create a Parent account, and sign the Parent Compact before the teen's full feature set unlocks.
• Under-13 accounts are not permitted on Schools deployments — they are routed to the Family product (separate consent flow).

12.3 FERPA (US schools)

• HiBFF only processes data necessary to deliver the programme (US Department of Education "school official" exception).
• No teen identifiers are returned to the school. Schools receive aggregate cohort data only.
• Schools may request bulk data export or deletion at any time via

  support@hibff.com

  .

12.4 Other surfaces

• Twilio SMS 2FA on prod admin; bypass only via env-secret

  TWO_FA_TEST_BYPASS_TOKEN

  (dead code in prod where the env var is unset).
• Empathic Handover Protocol (separate doc) intercepts crisis-language signals, pauses AvA, surfaces region-appropriate professional help, and notifies the parent.

13. Onboarding a school in 14 days

/api/admin/schools/create

14. Success metrics & internal SLAs

14.1 Programme-level

• ≥ 60 % of enrolled teens complete the OCEAN onboarding within 7 days.
• ≥ 30 % of teens reach challenge 5 within 30 days.
• ≥ 15 % complete all 20 challenges (vault unlock) within 6 months.

14.2 CRM-level

• Median letter → first open: < 36 hours.
• Median letter → reply for ★★★ Gives priority: < 21 days (target).
• Bounce rate: < 5 % (sustained over a 60-day window).

14.3 Operational SLAs

• AvA chat latency: P95 < 2.5 s, P99 < 4 s.
• Backend availability: 99.9 % rolling 30-day.
• Empathic Handover trigger → parent notification: < 60 s end-to-end.

15. Frequently asked questions

Q: Can a teacher see what a teen wrote to their AvA? A: No. Ever. Teen conversations are end-to-end private; only the teen and (post-handover, in crisis only) the parent see them.

Q: Can a parent override consent for the teen? A: A parent can revoke consent (which terminates the teen's access). A parent cannot grant consent unilaterally — the teen must also sign the Teen Compact.

Q: What happens to a teen's NFTs at 18? A: A guided wallet handover unlocks the keys. The teen takes full custody. HiBFF retains no copies of private keys.

Q: How does HiBFF Gives stay sustainable? A: 45 % of the city's paying parent subscriber revenue funds the city's free school programme. Cities where parent uptake is strong fund cities where it isn't.

Q: What if a mayor changes mid-year? A: The contract is with the city (or the public-school district), not the individual mayor. Continuity is preserved.

Q: Can a school admin export student data? A: Schools cannot export individual teen data — they only see aggregates. Parents can export their own teen's data via the Parent Dashboard.

Q: What languages does AvA support? A: English (primary). Spanish (Q3 2026). The conversational onboarding uses native browser TTS, so any locale supported by the user's browser will at least speak — but the OCEAN scoring model is currently English-trained.

16. Glossary

• AvA — the AI conversational partner. Browser-rendered with idle-loop video + native TTS.
• Charter — the umbrella term for the Parent Compact + Teen Digital Compact.
• Custodial Vault — the HiBFF-held wallet that mints achievement NFTs on behalf of the teen.
• Dynamic Challenge Engine — the Phase A-I library + assignment + completion + analytics system.
• HiBFF Gives — the civic-donation arm: free programme to underserved cities.
• OCEAN — the Big-Five personality model (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism).
• Outreach Tracker — the admin CRM tab inside the Schools Command Centre.
• Postmark — transactional email vendor used for all outbound mail and inbound parsing.
• Sankey — flow-diagram visual showing how teens move through the 20-challenge journey.
• Sub-admin — non-master admin role with read/write access to schools-engine endpoints but not to vault/billing surfaces.

HiBFF — Brave Friends Forever. Brave conversations, in a safe place.