VitaForge Platform

VitaForge is a premium, AI-enabled longevity and personalized nutrition platform that ingests wearable, lab, biometric, and lifestyle data to deliver explainable protocol guidance with clinical-grade confidence. This repository covers the entire MVP stack—from secure onboarding and sessions to deterministic protocol generation, trends/history storytelling, and demo personas tailored for pitch-ready storytelling.

What’s inside

• apps/web/ – Next.js App Router UI surfaces (landing, auth, onboarding, dashboard, today’s protocol, check-ins, biomarkers, trends, and admin/demo controls).
• src/ – Shared domain models, UI primitives, and services for auth, onboarding, protocols, trends, demo personas, and integration placeholders.
• prisma/ – PostgreSQL-ready schema, deterministic seed script (npm run seed), and client-ready types.
• docs/ – Multi-page reference material covering architecture, domain models, the protocol engine, UX, local dev, and the roadmap.
• tests/ – Vitest coverage that guards protocol heuristics, onboarding validation, trend aggregation, and demo persona sanity.

Core value pillars

1. Explainable guidance – src/services/protocolEngine normalizes payloads, evaluates heuristics (sleep, stress, protein/hydration behavior), and emits recommendations with rationale, assumptions, missing-data notes, and safety flags.
2. Longitudinal storytelling – src/services/trendInsights delivers sleep, stress, recovery, adherence, biomarker, and derived optimization trends plus confidence narratives for investors.
3. Premium UX – Glassmorphic cards, considered typography, consistent spacing, and thoughtful empty/loading states across dashboard, trends, and protocol surfaces.
4. Demo-ready data – Seeded personas cover executive stress, fitness recovery, and midlife longevity profiles with wearables, labs, check-ins, adherence logs, trends, and protocol plans that you can explore from /admin/demo.
5. Future-proof integrations – Placeholder interfaces for Apple Health, Oura, Whoop, Garmin, Fitbit, labs, and genetics make it easy to plug real connectors later.
6. Durable orchestration – Prisma-backed events/jobs describe every intake, ingestion, state-change, and notification opportunity while the npm run jobs:run runner and admin console surface retries, failures, and queue depth for credible demos.

Getting started (from repository root)

1. npm install (or npm ci for clean worktrees)
2. npm run setup (generates Prisma + pushes the schema)
3. npm run seed
4. npm run dev
5. npm run lint
6. npm run test

Reliability tips

• npm run reinstall wraps clean:outputs and npm install so you can refresh the repo-local cache without deleting node_modules.
• npm run ci mirrors GitHub Actions: it generates Prisma, lints, and runs Vitest in one command, using the repo-local SQLite (DATABASE_URL=file:./dev.db).
• npm run env-check spots path issues (OneDrive, spaces, syncing) before you install, so you can fix the location before locks appear.
• Windows/OneDrive users: pause file syncing before reinstalling, run npm run clean:outputs to clear .next/.turbo/.npm-cache, and if locks persist remove apps/web/.next manually before rerunning npm install.
• The .npmrc file pins npm’s cache to ./.npm-cache. Override with NPM_CONFIG_CACHE or npm --cache=./.npm-cache if you prefer another location. Keeping the cache inside the repo avoids system-wide permission issues.

Useful repo commands

• npm run db:push – push Prisma’s schema to whatever DATABASE_URL you have configured (SQLite or Postgres); needed before seeding with new databases.
• npm run ci – runs Prisma generate, lint, and Vitest in one command; matches the GitHub Actions workflow.
• npm run jobs:run – claims pending background jobs (ingestion, protocol recalculations, admin snapshots) with the same handlers wired into the API and surfaces job outcomes in the console.
• .npmrc pins npm’s cache to ./.npm-cache, keeping installs inside the repo; override with NPM_CONFIG_CACHE/npm --cache if you prefer another location.

Environment expectations

• Copy .env.example to .env.local and keep the values private. The app enforces required variables via src/lib/config.ts, and the same file exposes the demo-mode toggle (ENABLE_DEMO_MODE), log level, and session cookie settings (see docs/LOCAL_DEV.md).
• Prisma targets PostgreSQL out of the box, but you can point DATABASE_URL at SQLite (file:./dev.db) for quick testing. Always run commands from the repository root so relative paths remain portable.

Auth & session model

• Sessions live in AuthSession rows and are resolved via src/server/session.ts, which returns sanitized SessionUser objects (hashed passwords are never exposed, the role is explicit, and demo personas are flagged). Client routes like /admin, /api/checkin, /api/biomarkers, and /api/labs/parse now always call this helper before mutating user state.
• Operator/admin surfaces rely on src/lib/access.ts for gating, and demo persona switches respect ENABLE_DEMO_MODE (otherwise only operators can impersonate demos). Audit records capture both the action and whether an operator or the demo flag triggered it. See docs/AUTH_SESSION.md and docs/TRUST_GOVERNANCE.md for details.

Demo personas & exploration

• Run npm run seed to load the three curated personas (executive stress, fitness recovery, midlife longevity). The script wipes and recreates the demo data every time so you can reseed safely.
• Visit /admin/demo in the running app to view persona status, read caveats/missing-data notes, and switch your session into any persona.
• Each persona ships with wearable snapshots, biomarker panels, trend snapshots, check-ins, adherence history, and deterministic protocol recommendations that align with their goals.

Docs & next reading

• docs/ARCHITECTURE.md
• docs/DOMAIN_MODEL.md
• docs/PROTOCOL_ENGINE.md
• docs/UX_OVERVIEW.md
• docs/ROADMAP.md
• docs/LOCAL_DEV.md
• docs/UX_OVERVIEW.md (data-confidence storytelling, investor copykeepers, and premium landing iterations)
• docs/AUTH_SESSION.md
• docs/CONNECTOR_ARCHITECTURE.md
• docs/CONNECTORS.md
• docs/LAB_GENETICS_INGESTION.md
• docs/REOPT_NOTIFICATIONS.md
• docs/ADMIN_ANALYTICS.md
• Run npm run clean:outputs to flush repo-local build artifacts (.next, .turbo, .npm-cache, dist, out), especially helpful on Windows/OneDrive before reinstalling dependencies. Node modules remain untouched. Documentation in docs/LOCAL_DEV.md explains the workflow and Windows recommendations.

Tech stack summary

• Next.js App Router + TypeScript + Tailwind + shadcn/ui
• Prisma + PostgreSQL-ready schema
• React Hook Form + Zod
• Recharts for charting
• Vitest for tests, ESLint + Prettier for quality