Tech Spec — detailed requirements

V1 scope assumptions

·Mobile web app, entered from a shared link.
·Magic-link authentication (email, no password).
·Assessment calculations come from third-party APIs (Human Design, astrology, Enneagram). Work Skills via a licensed source; Strength via an in-house assessment under validation.
·Only the final Clarity Code report is AI-generated; all other results are computed or templated.
·No payment in V1.
·Coach view = email/SMS notification + a basic web dashboard with notes and transcript upload.
·Assessment order: Energy → Motivation → Values → Work Skills → Strength → Clarity Code.

Non-functional requirements

Performance

LCP under 2.5s on a mid-range Android. No layout shift on bodygraph render.

Accessibility

WCAG 2.2 AA. Every assessment screen reachable by keyboard, screen-reader labeled.

Save & resume

Every answer autosaves. Cold-resume on any device using the user's account.

Privacy

Birth data and answers are personal — encrypted at rest, never used for marketing.

Calm by default

One focal per screen. No notification badges, no streak mechanics, no upsell mid-flow.

Growable

Clarity Code report is structured so new chapters can be added without redesign.

Integration points

Human Design API (bodygraph)Selected

Enneagram assessment — API or custom buildTo decide

Astrology API (sun/moon/rising, transits)To select

Predictive Success Assessment (Work Skills)License pending

In-house Strength assessment engineUnder validation

AI provider for Clarity Code generationTo select

Geocoding / map provider for birth locationTo select

File storage for coach transcripts & uploadsRequired for V1

Auth — magic linkRecommended

Email — transactional to Kate and participantRequired for V1

SMS — transactional to Kate and participantRequired for V1

Analytics — privacy-firstTBD

Error monitoring / observabilityTBD

Consent & cookie managementTBD

Kate's CRM / scheduling tool syncFuture

Payments (post-V1)Out of scope V1

Risks & how we test them

TS-2026 · Risk Matrix · 15 identified

ASMT-01

In-house Strength assessment may not hold up vs. the original

Test protocol

Run full codes with and without it; compare resonance and accuracy.

PROD-02

People drop off before finishing all five

Test protocol

Instrument step-by-step completion; watch Energy→finish conversion against the ≥70% goal.

INFRA-03

Third-party API cost/latency/availability at volume

Test protocol

Load + cost modeling against expected usage; define fallback behavior.

AI-04

AI report reads generic or inconsistent

Test protocol

Review sample reports for voice and accuracy; decide generative vs. assembled.

DATA-05

Birth-time precision affects chart accuracy

Test protocol

Decide required vs. optional; validate degraded path if optional.

LEGAL-06

Predictive Success Assessment licensing terms shift cost or access

Test protocol

Lock pricing, rate limits, and termination terms in writing before V1 commits to it.

AUTH-07

Magic-link friction (spam folders, expired links) blocks return visits

Test protocol

Track link-click rates and resume success; tune expiry, sender reputation, and retry UX.

LEGAL-08

Personal/birth data attracts privacy obligations (GDPR-style requests, breach risk)

Test protocol

Document retention, export, and delete flows; encrypt at rest; legal review before launch.

AI-09

AI-generated report could surface inaccurate or harmful framing

Test protocol

Human-in-the-loop review for early reports; guardrails + a flag-for-Kate path on every report.

SCALE-10

Coach becomes a bottleneck as volume grows

Test protocol

Measure time-per-participant; design dashboard triage and templated notes before scale.

AUTH-11

Single-coach assumption breaks when a second practitioner joins

Test protocol

Confirm V1 auth + record ownership model can extend to multi-coach without a rewrite.

VENDOR-12

Vendor lock-in on Human Design / Enneagram APIs

Test protocol

Abstract integrations behind an internal interface; keep raw inputs so results can be regenerated.

DATA-13

Shared device or family using one link contaminates results

Test protocol

Decide account-per-person rule; detect re-entry and prompt for a fresh session.

PROD-14

Mobile-only assumption may exclude desktop-first users (Kate's referrals, older audience)

Test protocol

Validate device mix in early cohorts; confirm responsive desktop view is acceptable for V1.

SCOPE-15

Scope creep from 'just one more assessment' requests

Test protocol

Hold the five-step contract; route new ideas to a post-V1 backlog with explicit criteria.

End of section · hover a card for mitigation strategy

Key scenarios · Given / When / Then

Landing & account creation

Arrive from a shared link

GivenA person opens the shared link on their phone

WhenThe landing screen loads

ThenThey see a warm welcome and a single primary action to begin — no login or password is requested up front

Enter basics with validation

GivenThe person has started onboarding

WhenThey enter full name, birth date, and birth time

ThenName is required and non-empty; birth date must be a valid past date; birth time must be a valid time

Open: is birth time required, or can someone proceed 'time unknown' with a degraded Energy result?

Pin birth location on a map

GivenThe person is on the birth-location step

WhenThey search for a place or drop a pin

ThenThe selection resolves to a named place plus coordinates; city-only selections are accepted

Open: which map/geocoding provider? (cost driver)

Create account via email + magic link

GivenThe person has entered basics and location

WhenThey submit their email

ThenAn account is created keyed to that email, a magic link is sent for verification and future resume, and their inputs persist immediately

Open: must the link be clicked before seeing Energy, or only for return visits?

Returning via magic link

GivenA person has an account and requests access

WhenThey open a valid, unexpired magic link

ThenThey are signed in and returned to where they left off; an expired or reused link prompts a fresh one

Open: link expiry window?

Invalid email

GivenThe person is on the email step

WhenThey submit a malformed email

ThenThey see an inline error and cannot proceed until it is valid

Energy result (the hook)

Generate Energy from birth details

GivenThe person has submitted name, birth date, birth time, and location

WhenThe system requests their Energy result

ThenLife Path is derived from the birth date; Human Design (bodygraph, profile, type, strategy, signature, not-self) and sun/moon/rising are retrieved from third-party APIs; the combined Energy result shows with no questions answered and progress reads 1 of 5

Energy is a taste, not the full data

GivenThe Energy result has generated

WhenIt displays

ThenThe person sees a resonant, partial view designed to earn the next step

Open: exactly how much is shown vs. held back (product decision)

External API is slow or fails

GivenThe system has requested third-party data

WhenThe API is slow, errors, or returns incomplete data

ThenThe person sees a calm waiting or graceful-failure state; the request can retry or queue without losing inputs

Open: acceptable wait before fallback? retry policy?

Birth time unknown (if allowed)

GivenA person did not provide a birth time

WhenEnergy generates

ThenThe system produces the parts that don't require exact time and clearly notes what is limited

Assessment loop — Motivation, Values, Work Skills, Strength

Bridge screen before an assessment

GivenThe person is about to begin an assessment

WhenThe bridge screen appears

ThenIt names the step in plain language, says what it measures and roughly how long; before Motivation it advises ~150 questions, 15–20 minutes, find a quiet place

Answer one question at a time

GivenThe person is inside an assessment

WhenThey answer a question

ThenOnly that question is shown, the rest of the app is hidden during intake, and within-assessment progress is visible

Autosave

GivenThe person is partway through an assessment

WhenThey answer each question

ThenProgress saves continuously

Open: save every answer vs. every N answers (write-volume tradeoff)

Resume after interruption

GivenThe person left an assessment at question 42 of 150

WhenThey return via account or magic link

ThenThey see 'Welcome back — resume at 42' and continuing returns them to the exact question

Score via integration

GivenThe person completed all questions in an assessment

WhenThe system scores it

ThenMotivation returns Enneagram type + wing; Values returns results across Personal, Family, Relationship, Business; Work Skills returns Visionary/Operator/Processor/Synergist; Strength returns a result from the in-house assessment

Open: exact vendor and return shape per assessment; is in-house Strength scoring defined or still validating?

Values is guided, not vendor-scored

GivenThe person reaches Values

WhenThey work through it

ThenThey complete a guided values exercise across the four pillars and the result reflects back as their decision-making blueprint

The carrot (Motivation result)

GivenThe person completed Motivation

WhenThe result displays

ThenIt shows Enneagram number and wing framed as Motivation, and offers 'go deeper into your number' or 'keep going' — neither loses progress

Progress & the Clarity Code

Track progress across five steps

GivenThe person is moving through the journey

WhenThey complete each step

ThenA persistent indicator reflects how many of five are done; remaining steps read as momentum, not a chore

Generate the Clarity Code

GivenThe person has completed all five assessments

WhenThe system generates the final report

ThenIt composes the five results into one AI-generated report that reads as a whole, integrated personal operating system, and saves to both the person's account and the coach's record

Open: fully generative or AI-assembled from approved building blocks? Reviewed before the person sees it, or instant?

Re-read the report

GivenA person has a generated Clarity Code

WhenThey return later

ThenThey can open and re-read all five chapters and navigate to any section

Coach view

New signup appears for the coach

GivenA person creates an account during onboarding

WhenThe account is created

ThenThey appear in the coach dashboard as in-progress

Notify the coach on Energy

GivenA person completes their first step, Energy

WhenThat step is marked complete

ThenThe system emails/texts the coach that the person finished Energy, including how they scored

Open: which Energy fields are in the notification?

Coach views a person's Energy result

GivenA person has completed Energy

WhenThe coach opens that person's record

ThenThey see the Energy result before the rest is finished

Coach dashboard list

GivenThe coach is signed in

WhenThey open the dashboard

ThenThey see people with their progress and available results

Open: coach auth method? single coach or multiple in V1?

Coach adds notes after the code exists

GivenA person has completed their Clarity Code

WhenThe coach adds a note to their record

ThenIt saves timestamped and attributed; earlier notes remain in order

Open: notes coach-only or person-visible? editable/deletable?

Coach adds an integration transcript

GivenA person has a Clarity Code

WhenThe coach adds a transcript to their record

ThenIt stores dated and labeled, alongside the code and notes

V1 stores only — no auto-update of the code. Open: paste vs. upload? file types?

Cross-cutting concerns

·Data sensitivity: birth data + results are personal — privacy, retention, consent handling required.
·Email/SMS delivery: transactional provider for magic links and coach + participant notifications.
·Shared device / multiple people from one link: handle cleanly.
·Accessibility target for the web app: confirm.
·Abandoned journeys: re-engagement email, or nothing in V1?
·Analytics: completion rate, Energy→finish conversion, 30-day return.

Explore the blueprint