Wellbeing scoring platform — AI-powered psychological insights

Industry

Wellbeing / coaching insights

Type

Assessment + recommendation platform (non-diagnostic)

Role

Architecture + full-stack + scoring / LLM path

Scoring

Big Five · Attitude Index · K-means (4 clusters)

Stack

FastAPI · PostgreSQL · Next.js · OpenAI

Proof

Public marketing, admin RBAC, prompt + safety screens

Public copy says “psychological analysis.” The contract that matters is non-diagnostic: self-report in, scores and short habits out. Marketing also lists habit tracking; this admin session showed habit / mood / reflection counts at zero.

The problem

Most “AI for psychology” demos are a chatbot that talks like a clinician. That fails the moment you need something you can operate:

• Questionnaires hardcoded in the frontend, so a new version is a deploy
• Personality labels invented in prose, with no score table you can audit
• Recommendations that leak diagnosis, medication or therapy language
• No coach vs admin split — everyone sees everyone
• No place to change the model, the system prompt or the safety list without shipping code

A therapist-shaped LLM is the wrong product. The hard parts are versioned questionnaires, a scoring engine, filters on model output, and three roles that must not see each other’s data.

Business requirements

One path for a visitor: land, understand Big Five and Attitude Index, sign in, complete an assessment, see charts. One path for ops: users, assessments, OpenAI keys, system prompt, prompt packs and safety guardrails. Scoring and clustering stay in the backend. The model writes habits after scores exist.

This page does not publish invented wellbeing percentages or “users improved X%.” The engineering claim is a complete surface map.

The solution

FastAPI (async SQLAlchemy, Alembic) owns auth (JWT and email OTP), questionnaires, assessments, scoring, clustering, recommendations and analytics. PostgreSQL is the system of record. Next.js 14 (App Router, Tailwind, Recharts) renders public marketing, login, dynamic questionnaires, results and admin. OpenAI writes recommendation copy after scores exist. scikit-learn K-means assigns one of four cluster labels.

Three audiences, one codebase:

• Visitors — Features, About, Login, Get Started
• Users — questionnaires, assessments, results
• Admins — users, assessments, analytics, AI settings (API, prompt engineering, safety)

Coaches are a first-class role with assignment rows. This session had zero coaches and four users without a coach — the assignment UI exists; it was unused here.

How the system flows

Behavior signals feed models that score exchange outcomes — analytics and trading interfaces consume the same event spine.

flowchart LR
  Events[Market behavior events] --> Feat[Feature pipeline]
  Feat --> Model[Predictive models]
  Model --> Score[Risk or behavior score]
  Score --> UI[Trader or ops UI]

Architecture

The model is a writer of habit text. Scores are rows. Safety is a filter, not a hope.

flowchart TB
  Feed[Event feeds]
  Proc[Processing and features]
  Store[(Time-series store)]
  Models[Model runtime]
  App[Exchange UI APIs]
  Feed --> Proc
  Proc --> Store
  Store --> Models
  Models --> App

Key components

What the public product actually covers

The marketing site is the same Next.js app, not a second brochure:

• Features — Big Five, Attitude Index (optimism, grit, social connections, stress resilience, meaning), interactive dashboards, personalized recommendations, habit tracking, research-backed insights
• Framework — Demographics, Lifestyle, Family Context, Behavioral
• How it works — complete assessment (~15–20 minutes in copy) → AI analysis → insights
• Journey — Questionnaires, Assessments, Analytics as three CTAs

Public personalization cards advertise context-aware packs (urban/rural, age, lifestyle), prompt engineering, cultural adaptation, a recommendation engine, lifestyle-specific packs and an ethical AI framework (non-clinical, privacy first, empowerment). One card says “GPT-4 Powered.” The admin configuration in this session was GPT-4o. This page treats that as vendor configuration, not a published clinical model.

A six-step explainer sits on the same site: profile analysis, context detection, prompt-pack selection, AI generation, safety filtering, personalized delivery — plus a privacy note that data is used to generate recommendations and is not shared with third parties. That is product copy, not a certification.

Admin and RBAC

Signed-in chrome: Home, Dashboard, Questionnaires, Assessments, Analytics, Admin, Logout.

This admin session:

• 4 users (4 active), 0 coaches, 17 assessments (1 completed), habits / mood / reflections at 0
• User–coach assignments: 0 with coaches, 4 without — “No users assigned to coaches yet”
• User management — filter by role, search, Assign Coach / Edit / View / Delete. Demo rows use example.com addresses
• All assessments — filter by status and user id; most rows in this capture were in_progress
• Analytics — 7 assessments in that view, 1 completed, 6 in progress, 14% completion. That is this session’s book, not a published outcome
• Cohorts — create form with name and JSON filter; none created yet

Model, prompts and safety

AI settings is a product screen, not a .env file. Three tabs: API Configuration, Prompt Engineering, Safety Guardrails.

• API — OpenAI key stored masked (sk- …), model name GPT-4o, status Active. Keys are not echoed in full
• System prompt — admin-editable. The captured prompt tells the model to write practical, non-clinical recommendations, stay under 150 words, and avoid religion, caste, political events and clinical diagnoses. This page does not reprint the full prompt
• Prompt packs — modular add-ons selected from demographics and lifestyle (India tier/rural, remote work, Gen-Z, students, and similar packs in the service layer)
• Safety — checklists for clinical terms, medicalized vocabulary, diagnostic verbs, medication, therapy modalities, severity language, pathology adjectives, self-harm redirection and substance-abuse labels, plus tone rules (warm, non-stigmatizing, culturally sensitive)

Scoring and data

Questionnaires are versioned objects with JSON schema — not hardcoded React forms. Reverse-keyed items flip before aggregation.

• Big Five — openness, conscientiousness, extraversion, agreeableness, neuroticism
• Attitude dimensions — optimism, grit, social support, stress management, meaning
• Attitude Index — weighted composite, then normalized
• Clusters — K-means, four product labels: Balanced, Motivated, Vulnerable, Highly Stressed

Traits and scoring rules live in questionnaire JSON rather than separate tables, so a new version does not require a migration. Scores, clusters and recommendations are first-class rows tied to an assessment.

Identity: users with role user / coach / admin. Coaching: coach_assignments with one active coach per user. Content: questionnaires, questions, options, sections. Analytics: cohorts and members with JSON filters. Ops: API configs, audit log, feature flags. Habit / mood / reflection tables exist; this capture had empty counters.

Engineering challenges

• Questionnaire as data — new versions without a frontend rewrite
• Scoring you can explain — reverse keys and weights in config, not in a prompt
• LLM leakage — clinical language is a content bug, same class as a wrong score
• RBAC — coaches must not enumerate other coaches’ users
• Honesty in copy — “psychological analysis” on the landing vs non-clinical in admin safety

How those were solved

Assessment submit triggers scoring, then clustering, then recommendations. Admin owns the model, the prompt and the filter list. Coach APIs join through assignment rows. The dashboard reads score tables. The model does not recalculate traits in prose.

My role

Architecture + full-stack + scoring / LLM path. API and schema, scoring services, recommendation guardrails, Next.js public and admin surfaces, role boundaries. Live user rows stay off this page.

Technology stack

These technologies are the documented stack. This page does not add engines, certifications or habit UIs that were not in this capture.

Production considerations

• Wellbeing data minimization and consent on exchanges.
• Separate analytics plane from identifiable user profiles where required.

Engineering outcomes

No invented completion rates or “users became happier.” What this system actually established:

• A public path from Features / How it works / Journey into login and assessments
• A pipeline: questionnaire → assessment → Big Five / Attitude Index → cluster → filtered recommendations
• Admin that can set OpenAI model and key, edit the system prompt, and toggle safety filters
• User management with coach assignment, even though this session had no coaches yet
• Analytics and cohort JSON filters as ops surfaces — empty cohort list in this run
• An explicit non-diagnostic boundary in the safety UI, not only in a footer

Screenshots

Architecture on this page is the HTML diagram above. Related writing: Why India must take psychology seriously.

Architectural insight

A wellbeing insights product is a scoring and state machine that sometimes uses a language model. If the model owns the diagnosis, you do not have a product you can defend. If PostgreSQL owns scores and the LLM only writes habits through a filter, you do.

Disclaimer: Wellbeing scoring platform is software for self-reported insights and habit suggestions. It is not a diagnostic device, not psychotherapy, and not a substitute for a qualified clinician. Nothing here is a medical opinion. OpenAI capabilities are described as advertised in this admin configuration.

FAQ — buyer & architecture questions

Ten common questions about this case study, fit, and engagement.