stateOS

StateOS is the world's first state engineering platform: track internal state, diagnose drift, and intervene in real time.

stateOS treats "feeling off" as a solvable, trackable problem. It measures your Recovery Window — the time between noticing you've drifted from your baseline and getting back to it — and gets you there faster with a diagnostic flow and a library of short, timed protocols grounded in nervous-system regulation (HRV, vagal tone, paced breathing).

---

Table of Contents

• Overview
• Core Concepts
• Tech Stack
• Project Documentation
• Getting Started
• Environment Variables
• Project Structure
• Database
• Scripts
• Science & Content Policy
• Contributing
• License
• Acknowledgments

---

Overview

Most wellness apps ask you to log a mood. stateOS asks a narrower, more actionable question: when something throws you off, how fast do you get back? That single metric — the Recovery Window — is the app's north star, and everything else (the State Audit, the Diagnostic Engine, the Protocol Library) exists to make that number smaller over time, without ever treating a bad reading as a failure.

Core Concepts

• State Audit — a 5-dimension check-in (Energy, Clarity, Emotional Stability, Identity Alignment, Environmental Match), 1–5 scale, that establishes a baseline and flags drift.
• Diagnostic Engine — a short decision tree (max 5 questions) that locates where a disruption started — environment, perception, internal state, identity, or behavior — and routes to the right intervention. Runs deterministically first; falls back to an AI-assisted classification only for genuinely ambiguous free-text input.
• Protocol Library — six short, timed interventions (33-Second Reset, Heart Coherence Switch, Instant Realignment Protocol, Full-Body Frequency Flush, Highest Timeline Lock-In, Five Micro-Alignment Cues), each closing out a Recovery Window instance.
• Daily Architecture — a lightweight morning/afternoon/evening structure (3 min / 1 min / 2–3 min) for maintaining baseline rather than only reacting to drift.
• Recovery Window — the core metric. Computed server-side as a generated Postgres column, tiered from Instant (≤60s) to Extended (2+ hrs), never presented with red/green pass-fail framing.

Tech Stack

• Framework: Next.js 15 (App Router), TypeScript
• Database: Supabase (Postgres + Row-Level Security)
• ORM: Drizzle ORM
• Client state: Zustand (UI state) + TanStack Query (server state, optimistic writes)
• Styling: Tailwind CSS + shadcn/ui
• AI: Google Gemini API (gemini-2.5-flash for structured classification, gemini-2.5-pro for reflective prompts), proxied server-side via Supabase Edge Functions — the API key never reaches the client
• Hosting: Vercel

Project Documentation

Doc	Description
docs/ARCHITECTURE.md	System design, data flow, dual-mode pattern
docs/API.md	API routes + db.ts data layer reference
docs/DATABASE.md	Schema, migrations, RLS policies
docs/PROTOCOLS.md	Protocol library, science tiering, player logic
docs/DEPLOYMENT.md	Environment setup, build, deploy
docs/CONTRIBUTING.md	Dev workflow, conventions, linting
docs/USER_GUIDE.md	End-user feature walkthrough

Getting Started

Prerequisites

• Node.js 20+
• npm or pnpm
• A Supabase account and project
• A Google AI Studio API key for Gemini

Installation

git clone https://github.com/your-org/stateos.git
cd stateos
npm install

Supabase Setup

1. Create a new Supabase project.
2. Run the schema migration from docs/stateOS_Technical_Specification_v2.md §4 (tables, RLS policies, indexes) plus the additions in docs/stateOS_Settings_Profile_Plan.md §2.
3. Seed the protocols table using the JSON blocks in docs/stateOS_Protocol_Content_Library.md.
4. Deploy the Edge Functions in supabase/functions/ (gemini-proxy, diagnose-drift, daily-reminder-cron, recovery-window-digest, identity-anchor-reflect, export-user-data, delete-account).
5. Set GEMINI_API_KEY as a secret on the Edge Functions — not in any client-exposed env file:

supabase secrets set GEMINI_API_KEY=your-key-here

Local Development

cp .env.example .env.local
# fill in the values described below
npm run dev

App runs at http://localhost:3000.

Environment Variables

Variable	Where	Description
NEXT_PUBLIC_SUPABASE_URL	Client + server	Your Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Client + server	Supabase anon/public key
SUPABASE_SERVICE_ROLE_KEY	Server only	Used for admin-level operations (e.g. account deletion cascade checks); never expose to the client
GEMINI_API_KEY	Edge Function secret only	Set via supabase secrets set, never in .env.local or any NEXT_PUBLIC_* variable

Project Structure

/app
  /(auth)
    /login
    /onboarding
  /(app)
    /today
    /audit
      /new
      /history
    /diagnose
    /protocols
      /[slug]
    /recovery
      /history
    /identity
      /anchors
      /compass
    /profile
    /settings
      /account
      /reminders
      /preferences
      /privacy
/supabase
  /functions
    /gemini-proxy
    /diagnose-drift
    /daily-reminder-cron
    /recovery-window-digest
    /identity-anchor-reflect
    /export-user-data
    /delete-account
  /migrations
/docs
  (see Project Documentation above)

Database

Eight core tables (state_audits, drift_events, protocols, protocol_sessions, identity_anchors, daily_architecture_logs, diagnostic_sessions, user_preferences) plus a profiles table for identity-facing data, all with Row-Level Security scoped to auth.uid(). Full schema, generated columns (Recovery Window computation, drift flags), and RLS policies are in docs/stateOS_Technical_Specification_v2.md §4 and docs/stateOS_Settings_Profile_Plan.md §2.

Scripts

npm run dev        # start local dev server
npm run build       # production build
npm run lint          # lint
npm run typecheck      # TypeScript check
npm run db:generate     # generate Drizzle types from schema
npm run db:migrate       # run pending migrations

Science & Content Policy

All in-app claims are tiered as either Established (peer-reviewed — HRV, vagal tone, polyvagal states, DMN, interoception) or Working Model (explanatory metaphor — frequency, signature frequency, coherent radiance), and this distinction is enforced at the component level via ScienceTierLabel, not left to individual copy edits. See docs/StateArchitecture_Science_Framing_Cheatsheet.md for the full policy and the specific source-material passages it was written to fix.

Contributing

This project is currently maintained as a solo/small-team build. If you'd like to contribute:

1. Fork the repo and create a feature branch.
2. Keep new content (protocol copy, notification text, etc.) consistent with the tone guidelines in docs/stateOS_Protocol_Content_Library.md §1 and the science-tiering rules above.
3. Open a pull request with a clear description of the change.

License

MIT — see LICENSE.

Acknowledgments

The Protocol Library and Diagnostic Engine framework are adapted from State Architecture: The Foundational Guide to Human State Engineering, with claims re-tiered and re-cited to keep established science and practice metaphor clearly separated throughout the app.