05
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
Auth — magic linkRecommended
Email — transactional to Kate and participantRequired for V1
SMS — transactional to Kate and participantRequired for V1
Analytics — privacy-firstTBD
Data model
Person
id, name, birth_date, birth_time, birth_location {label, lat, lng}, email, created_at, status
Account
bound to email; magic-link sessions
AssessmentRun
id, person_id, type, status, progress {current, total}, answers[], result {…}, timestamps
ClarityCode
person_id, generated_at, report_content, source_run_ids[]
CoachRecord
person_id, notes[] {author, text, created_at}, transcripts[] {label, content, added_at}
Notification
type, person_id, sent_at, payload
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.
Risks & how we test them
In-house Strength assessment may not hold up vs. the original
TestRun full codes with and without it; compare resonance and accuracy.
People drop off before finishing all five
TestInstrument step-by-step completion; watch Energy→finish conversion against the ≥70% goal.
Third-party API cost/latency/availability at volume
TestLoad + cost modeling against expected usage; define fallback behavior.
AI report reads generic or inconsistent
TestReview sample reports for voice and accuracy; decide generative vs. assembled.
Birth-time precision affects chart accuracy
TestDecide required vs. optional; validate degraded path if optional.
Explore the blueprint