> ## Documentation Index
> Fetch the complete documentation index at: https://fit4lifecare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture & Stack

> How Fit4Life OS is built: one Next.js app with multiple experiences, Neon Postgres as the source of truth, Upstash Redis for conversation state, and Twilio + Claude + Clover/Uber adapters at the edges.

Fit4Life OS is a **single Next.js application** that serves several distinct experiences from one codebase and one database. This page is the maintainer's map of how the pieces fit together.

## One app, several experiences

| Path               | What it is                                    | Auth   | Data source           |
| ------------------ | --------------------------------------------- | ------ | --------------------- |
| `/`                | Branded scroll-deck **proposal/pitch**        | Public | Static                |
| `/proposal`        | Long-form **send deck**                       | Public | Static                |
| `/app`             | High-fidelity **mock** CRM (demo theater)     | Public | Seeded mock data      |
| `/live`            | The **real OS** (the product)                 | Gated  | Neon Postgres         |
| `/ops`             | Legacy ops inbox (redirects to `/live/inbox`) | Gated  | Neon + Redis          |
| `fit4lifecare.com` | Public **SMS opt-in portal** + `/legal/*`     | Public | Writes `sms_consents` |

<Note>
  The mock `/app` demo and the pitch decks are intentionally separate from `/live`. Only `/live` and `/ops` touch real customer PII, and only they are behind the auth gate.
</Note>

## Stack

* **Next.js 16** (App Router, React 19, Turbopack). Dynamic route params are async (`params: Promise<{ id }>`). See `AGENTS.md`, this Next.js has breaking changes vs. older versions.
* **Tailwind CSS v4** (`@theme` tokens in `src/app/globals.css`), **TypeScript strict**, `@/*` → `src/*`.
* **Neon Postgres** (`@neondatabase/serverless`), the source of truth for `/live`.
* **Upstash Redis** (REST), SMS conversation store + automation flags; falls back to an in-memory `Map` when unconfigured.
* **Anthropic Claude**: the SMS bot brain and the in-OS assistant.
* **Twilio**: inbound/outbound SMS, routed through an A2P 10DLC Messaging Service.
* Hosted on **Vercel** (auto-deploy from `master`).

## The server-only boundary

Everything under `src/lib/server/**` is marked `import "server-only"` and must never be imported from a client component. Secrets are read only through `src/lib/server/env.ts`. Pure, client-safe analytics live in `src/lib/live-data/compute.ts`; the DB loaders live in `src/lib/live-data/index.ts` (React `cache()`'d, server-only).

## Request flows

<Steps>
  <Step title="Inbound SMS">
    Twilio POSTs to `/api/sms/webhook` → signature is verified → the message is persisted up front → the bot brain (`bot.ts`) runs its tool loop against `bot-tools.ts` → a TwiML reply is returned synchronously. The bot answers customers **via TwiML**, so the only outbound `sendSms` path is the ops manual reply.
  </Step>

  <Step title="Ops manual reply / takeover">
    `/live/inbox` → `/api/ops/reply` → `sendSms()` (routed through the Messaging Service when `TWILIO_MESSAGING_SERVICE_SID` is set). Sending auto-takes-over the thread.
  </Step>

  <Step title="OS screens">
    `/live/*` server components call the `live-data` loaders → Neon. Mutations go through gated, atomic API routes under `/api/live/*` and append an `audit_events` row.
  </Step>

  <Step title="Automation chain">
    reorder → `sendInvoice` (Clover adapter) → on payment (`onInvoicePaid`) → notify clinic/owner (Twilio) → optional Uber dispatch. Selection of stub vs. real provider happens only in `adapters/index.ts`.
  </Step>
</Steps>

## Auth gate

A single shared password (`OS_PASSWORD`) gates `/live` and `/ops`. `/login` sets a signed httpOnly session cookie (`OPS_SECRET` signs it); `src/proxy.ts` (Next 16 "proxy" = middleware) plus server-side checks enforce it. The ops API also accepts `Authorization: Bearer <OPS_SECRET>`. The pitch and mock `/app` stay public.

<Card title="Next: the data model" icon="database" href="/docs/architecture/data-model">
  See every Postgres table and why analytics are derived, not stored.
</Card>