From First Principles.

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 makes direction legible while there is still time to act.

Proactive personal health intelligence. Four domains. One connected system. One compounding intelligence layer.

Beneath all four domains is a unified homeostatic layer: glucose, blood pressure, core temperature, and respiratory rate. They are not four independent dashboards. They are observable expressions of one regulating system. As sensors improve, their history and interaction become the backbone of Portico's intelligence.

These were established early and reviewed throughout.

Established in April 2026, then made cloud-neutral as the system matured.

Zero to working infrastructure in a day.

Google Workspace, managed container and PostgreSQL infrastructure, Cloudflare DNS, Vercel connected to GitHub, Supabase with email auth only, PostHog, Sentry across three projects, and an Apple Developer account.

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.

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.

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.

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

FastAPI in a managed container runtime, PostgreSQL, Alembic migrations, and explicit health checks. Docker images were built locally; Python layer caching made that substantially faster during the first deployment.

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.

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

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.

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 → four 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.

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.

Mobile app actually talking to the production backend for the first time. Mobile → Supabase auth → backend → PostgreSQL — end to end, working.

Phase 6 had one job: make it dead simple for users to get data into Portico.

Every realistic source — Apple Health, lab reports, blood pressure machines, glucose monitors, scales, grip strength devices, DEXA scans, meal photos — had to flow into a single canonical schema with no user friction. The thesis was deliberate. Synthesis without ingestion is theater. Get the inputs right first.

The phase expanded mid-flight. The original charter was a HealthKit rebuild and manual entry polish. What shipped was a generalizable extraction architecture that turns any image or PDF into structured, canonical health metrics — and then validated that architecture against a second, structurally different source.

A complete rebuild of mobile HealthKit sync from first principles.

V1 had drifted. Multiple sync paths, inconsistent anchor handling, intermittent gaps in historical data. V3 collapsed it to a single runSync() call using native HKAnchoredObjectQuery, with per-metric anchors stored in AsyncStorage and a 13-week history window always-on. Pagination at 500 samples. Deduplication via ON CONFLICT (hk_uuid) DO NOTHING on the backend.

Three backend tables, one for each HealthKit sample shape: quantity, category, correlation.

V1 stayed untouched throughout the rebuild. V3 replaced it cleanly at cutover. Zero regression. No data loss. The discipline of “new version coexists with old until cutover” proved itself again.

The architectural centerpiece of Phase 6. A user uploads a blood panel, a BP machine screenshot, a scale reading, a DEXA scan, or a meal photo. The system extracts structured metrics mapped to a canonical schema.

Three layers, strictly separated: the LLM raw envelope, the post-processor, the final ExtractionResult. Each layer has one job. The boundaries are enforced, not aspirational.

A canonical vocabulary of 58 metrics across six categories. Each metric carries physiological plausibility bounds — not clinical reference ranges, which would imply medical judgment Portico doesn't make. Plausibility bounds answer one question: is this number physically possible for a human body. Numbers outside the bounds are rejected before they pollute the schema.

A file normalizer sits in front of every image and PDF, standardizing dimensions before the LLM ever sees the input. The reason was cost. The unexpected benefit was date-extraction consistency — raw inputs produced wildly different date parses depending on resolution.

Schema naming was locked early and propagated everywhere. Per-entry measured_at is when the measurement happened on the body. Envelope-level ingested_at is when Portico extracted it. The distinction matters: lab work measured weeks ago and uploaded today is not the same as a reading taken this morning. The schema reflects that.

Meals via photo landed at the end of the phase as the second validation source. Upload a photo of a meal. The system identifies items, estimates portions, computes per-item macros, surfaces a review screen with editable quantities, computes live totals as the user adjusts. Save. Done.

The extraction architecture didn't need to change to support meals. That was the point.

A phase this long surfaces every shortcut taken in prior phases. Three rebuilds happened quietly in service of the main work.

Production PostgreSQL connection pooling hardened: pool_pre_ping, pool_recycle, pool_timeout, plus a FastAPI lifespan warmup query. Removed an entire class of intermittent prod errors that previously looked like network flakes.

An early managed database connector deadlocked the async event loop under load. Replacing it with the standard async DATABASE_URL path removed the provider-specific runtime behavior and the deadlocks.

EAS secret management formalized via scripts/push-eas-secrets.sh with a thin Makefile wrapper. The Makefile remained the canonical interface for every backend, mobile, and deploy operation, growing past 500 lines in itself!

Phase 6 solved ingestion. Phase 7 had to prove that the resulting data could become useful. The boundary was explicit: stop celebrating connectivity and begin returning interpretation, context, and an artifact worth coming back for.

The phase produced three distinct intelligence paths—voice-to-structured data, blood reports, and CGM reports—while direct Oura and Dexcom integrations widened the source graph beneath them. Each path reused the canonical schemas built in May.

Voice entry became the fastest route into Portico. A single capture lifecycle serves bolt long-press, Siri, the iPhone Action Button, Control Center, and Back Tap. On-device SFSpeechRecognizer produces the transcript; the backend maps it into the same canonical metric vocabulary used by image and PDF ingestion.

The architecture is intentionally convergent: many doors, one room. Warm and cold launch paths differ, but listening, parsing, confidence handling, review, and commit do not. Low-confidence entries are flagged for review rather than silently discarded.

A parsed lab upload became a durable intelligence artifact rather than a table of extracted values. Portico groups markers physiologically, reconciles units, shows both laboratory and Portico context, compares prior panels when available, calculates biological age from the required inputs, and generates a plain-English report that can be reopened and shared.

Deterministic computation happens before narrative generation. The LLM is allowed to explain the prepared evidence; it is not allowed to invent the evidence. Report records, generation status, stored JSON/PDF artifacts, failure recovery, and provenance are all first-class parts of the feature—not implementation details hidden behind the screen.

CGM followed the Blood Report spine but required a time-series compute layer of its own. Raw CSV, Apple Health, and Dexcom readings converge into one canonical chronology. Deterministic analysis computes per-meal iAUC, peak, time-to-peak, return-to-baseline, daily rollups, overnight baseline, and dawn behavior.

Data-quality gates travel with every result. Truncated meal windows, unstable baselines, sparse capture, and censored return times are represented explicitly. The insight engine ranks only defensible findings, then the narrative layer explains those findings without promoting missing or low-confidence data into certainty.

Oura and Dexcom moved from connection concepts to direct provider integrations: OAuth sessions, encrypted tokens, sync state, repair jobs, webhook handling, normalized provider records, and automatic plus on-demand synchronization.

Direct feeds coexist with Apple Health rather than replacing it. That decision created the source-reconciliation problem Phase 8 would solve: the same physiological concept can arrive through different transports, devices, sampling methods, and calculation semantics.

Reports and cards were connected to a growing science library so users could move from a result to the mechanism behind it. Blood pressure, exercise, energy systems, chronotype, protein leverage, and the Portico architecture became reusable content—not copy trapped inside one screen.

This established a durable contract: every important output needs a concise interpretation, visible provenance, and a deeper explanation for the person who wants to inspect the reasoning.

Industry data is easy to collect and surprisingly hard to make personal. Phase 8 built the layer between raw history and useful judgment: a consistent way to answer what is happening now, what has changed, what this person has demonstrated before, and how much confidence the system has earned.

The result was not another score. It was a reusable assessment contract applied across eleven metrics and all four domains.

Resting heart rate, HRV, respiratory rate, Deep + REM sleep, Morning Daylight, visceral fat, VO₂ max, grip strength, ApoB, hs-CRP, and fasting insulin now share an intelligence architecture without pretending they share the same mathematics.

Each assessment can carry a recent state, multi-timescale personal baselines, statistically meaningful periods, demonstrated ability, physiological context, source provenance, data sufficiency, and confidence. Robust medians, means, smoothing windows, observation thresholds, and period rules are chosen per metric. Sparse blood and body measurements remain sparse; dense wearable streams earn temporal analysis.

A baseline is never fabricated from insufficient history. A device change is not automatically a physiological change. Missing days remain missing. These constraints make the engine less dramatic and more trustworthy.

Three reconciliation modes became explicit. Pooled metrics combine genuinely comparable sparse observations. Stitched metrics form a chronology across compatible sources while preserving seams. Separate metrics retain independent assessments when provider or method changes the meaning of the number.

This matters most when Oura appears directly and again through Apple Health. Portico deduplicates equivalent transports, preserves provider and calculation-method identity, and refuses to merge histories merely because two fields share a label.

The backend assessment contract now powers the same reusable card on domain homes, Home, and My Cards. Each card exposes three layers: Your intelligence, Your trends, and Science behind. Period charts preserve provisional states and source seams instead of drawing a falsely continuous line.

Home became a composition layer—For You Now, My Signals, and More For You—fed by ranked cards, staleness, celebrations, and report readiness. A persistent mobile domain cache keeps the experience responsive while the backend remains the authority for interpretation.

Protocols followed the same pattern: modular, evidence-backed structures with purpose, expected outcomes, time horizon, and what Portico can track. The surface can expand without rewriting the presentation contract.

The backend moved from a provider-specific deployment to a cloud-neutral runtime contract. The same Docker image, FastAPI commands, Alembic migrations, environment names, provider jobs, and health endpoints can move between infrastructure providers without branching business logic.

Terraform provisions the AWS path: ECR, VPC and subnet boundaries, an Application Load Balancer, ECS Fargate services and one-off tasks, private RDS PostgreSQL, Secrets Manager, CloudWatch logs and alarms, EventBridge provider-sync schedules, autoscaling, TLS, and mobile release controls.

The migration was allowlist-driven rather than a blind database copy. Active v3 tables moved; deprecated Sage-era tables and obsolete v1 paths were audited and retired. Version and git metadata travel with every deployment. Docker—not a cloud vendor—is the portability boundary.

From Phase 0 to closed beta in four weeks.
From closed beta to a full ingestion platform in four more.
From ingestion to synthesis, personal intelligence, and a multi-cloud production foundation in the eight weeks after that.

The pace is set by the work, not the calendar.

Spec-first. Test-backed. Gen AI coding as a primary instrument throughout.