THE BLUEPRINT

From First Principles.

Phase 0 through Phase 5 — a record of what we built, how we built it, and the decisions that shaped it.

Portico was born from a personal reckoning. A mother diagnosed with type 2 diabetes, a decade of reactive management — labs checked when symptoms appeared, advice given after decline was already underway. The system was not broken. It was designed for the wrong moment. It showed up late, by definition.

The conviction that followed: reactive systems are always late. Proactive systems are built on visibility. Visibility changes trajectory.

Portico exists to build that visibility — not as a passive data logger but as an active intelligence layer that reads signals, finds patterns, and tells the user the one thing worth doing next.

What We're Building

Proactive personal health and wealth intelligence. Five domains. Five threats. One compounding intelligence layer.

SageMetabolicMetabolic disease
ApexCardiovascularCardiovascular disease
DuskSleepNeurodegeneration
StillMindCancer / stress disease
GroveWealthFinancial fragility

Beneath all five domains: a unified homeostatic intelligence layer. The body defends five core variables above all else — glucose, blood pressure, temperature, respiratory rate, and pH. As wearables mature, continuous monitoring of these four signals becomes the backbone of everything Portico does. This is a long-arc thesis locked into the product architecture from the beginning.

Design Principles

These were established early and reviewed througout.

Slope over state. Trajectory matters more than snapshots. A glucose reading is less useful than a glucose trend. A metric inside "normal" range and worsening is more dangerous than a stable elevated one.
Titan discipline. One thing owns the screen. Severe visual hierarchy. No noise. Named for the Titan app — Apple-influenced aesthetic throughout.
Education as the floor. Users get value before connecting any device. Empty states are never errors.
Value exchange. We ask for data only when we can show the user exactly why it matters.
The app decides; the user acts. Portico's core UX contract. We never present menus. We surface the one right thing.

The Stack

Finalized in April 2026 after deliberate iteration and two key reversals.

MobileExpo SDK · React Native · HealthKit · Health Connect · Supabase Auth · Sentry
WebNext.js 15 · TypeScript · Tailwind · shadcn/ui · Vercel · PostHog · Sentry
BackendPython · FastAPI · GCP Cloud Run · Cloud SQL Postgres · Alembic · Docker · Dexcom OAuth2
InfraCloudflare · Supabase · EAS · pnpm workspaces · Turborepo

Key reversal 1: Custom auth → Supabase Auth. Data stayed in CloudSQL; clean abstraction layer separates the two. The right call.

Key reversal 2: Cloudflare Pages → Vercel Hobby. Better Next.js DX, PR preview deployments. Cloudflare Pages remains the escape hatch if costs scale.

Phase 0April 2026 W-1

Accounts & Foundations

Zero to working infrastructure in a day.

Google Workspace, GCP project with Cloud Run and Cloud SQL enabled, Cloudflare DNS, Vercel connected to GitHub, Supabase with email auth only, PostHog, Sentry across three projects, Apple Developer account.

Cloudflare SSL sequence matters — grey cloud first to let Vercel provision SSL, then orange cloud with Full SSL. Getting this backwards costs hours.

Phase 1April 2026 W-1

Repo Bootstrap

Monorepo at n007/portico.life — pnpm workspaces, Turborepo. Structure: apps/web, apps/mobile, services/backend, packages/ui, packages/core, packages/types.

@portico/tokens package locked here — design system tokens including all five domain colors. Makefile first version, grew significantly over the phases.

Phase 2April 2026 W-2

Marketing Website v1

The first public-facing surface. Built from a Figma Make export — a key discovery that changed the workflow entirely.

Figma MCP tools only support design files — a hard platform restriction. Figma Make had already generated a complete React/Vite codebase. Instead of rebuilding from v0, we integrated that export directly into apps/web, converting from Vite to Next.js.

Waitlist was intentionally deferred. Site launched without email capture — get the brand right first, wire the backend later.

Phase 3April 2026 W-2

Mobile App v1

The largest single phase. Expo bootstrap through authentication, 13 screens across 5 flows, HealthKit integration across all four active domains.

Navigation architecture: floating pill tab bar at bottom center. Center action button (bolt) — intelligent, rule-based, never presents a menu. Portico made the decision; the user acts.

Auth language locked: "Continue with Apple / Google / Email" and "Other ways to Continue" — no generic tech terms.

Supabase Auth with Apple Sign In, Google Sign In, and email/password. Session persistence. User classification: Foundation tier (onboarding + manual data) and Compound tier (data-rich, wearable-connected). Auto-promoted by data richness.

Phase 4April 2026 W-3

Backend

Two days of hard work to get the backend deployed and talking to CloudSQL.

FastAPI on GCP Cloud Run (us-west1), minimum 1 instance always warm. Cloud SQL Postgres via Unix socket — not TCP; Cloud Run requires the socket path. Alembic migrations. Docker images built locally, not Cloud Build — Python layer caching advantage is significant.

Key Debugging Wins

504 errors. Cloud Run cold start timeout. Fix: --min-instances=1. One gcloud command.

CloudSQL connection. Cloud Run needs Unix socket path in DATABASE_URL, not TCP. Deepest debugging rabbit hole of the entire build.

JWT verification. supabase.auth.get_user() replacing deprecated JWKS approach. Two env variables removed after confirming nothing else used them.

Sage Data Model

Seven tables: user_profiles, blood_markers, healthkit_readings, cgm_readings, meals, body_composition, sage_metabolic_state.

Bathtub model: five stages — Clear, Steady, Rising, Heavy, Cresting. Agency-forward language. No medical vocabulary. No fear.

Scoring: six components weighted — Glucose Regulation (25%), Insulin Sensitivity (25%), Lipid Metabolism (15%), Inflammation (15%), Metabolic Fitness (10%), Body Composition (10%). Missing components redistribute weight rather than penalizing.

Phase 5April 2026 W-4

Beta Readiness

The culminating phase: get website, mobile app, and backend to a level worthy of beta users, Apple review, Dexcom API approval, and investor conversations.

5A — Mobile Flows + HealthKit

Complete onboarding flow with all profile fields wired to backend. Foundation flow with compounding graph animation. HealthKit sync across all four domains. Navigator gate logic locked: session → register → profile → foundation → onboarding → home.

5B — Website Polish

Alpha feedback came in raw and direct: fonts too small, contrast absent, white space broken, content flow confused. Three design-level changes rebuilt the site from the ground up.

Full background treatment — Portico architectural image as atmospheric backdrop, no white sections breaking it. Typography scale dramatically increased. Content flow locked: Five Horsemen as the problem statement → five domains as the solution.

Eight new pages: Privacy, Security, Cookies, Contact, About, Science, Platform, and Hero Video concept film. Two treatment types: Atmospheric and Flat Dark.

5C — Mobile Polish

Home screen legibility overhaul. Domain intro pages polished. Auth flash eliminated. Content Intelligence Framework — schema, engines, three surfaces (Science, Protocols, Action).

Domain home framework v2: every domain home is the same product wearing different colors. Six layers — Header → Core Theme → Key Metrics → Meridian → Arc → Protocol. Core themes: Sage = Bathtub, Apex = Triangle, Dusk = Wave, Still = Tide.

5D — The Milestone

Mobile app actually talking to the real GCP backend for the first time. Mobile → Supabase auth → backend → CloudSQL — end to end, working.

Key Technical Learnings

  • Figma Make ≠ Figma Design. MCP tools only work on figma.com/design/ files. For Figma Make, screenshots or zip download only.
  • Framer URLs are not fetchable. JavaScript-rendered. Always get the source HTML or GitHub raw content.
  • Cloud Run + Cloud SQL. Unix socket, not TCP. Always. Min instances = 1 to eliminate cold start timeouts.
  • Local Docker builds for backend. Cloud Build is slow for Python — layer caching advantage is significant locally.
  • pnpm v10 security. onlyBuiltDependencies required in root package.json for sharp, @sentry/cli, protobufjs.
  • Branch strategy. Surgical fixes: main. Large feature: feature branch, merge same day. The real safety net is git commits, not branches.

From Phase 0 to closed beta in approximately four weeks of focused building.

Spec-first. Prompt-driven. Gen AI Coding as primary instrument throughout.

The blueprint is never finished.
It compounds.

Portico Life, Inc — porticolife.ai/blueprint