Corpus Mio: An Offline-First Nutrition PWA

📸Snapshot

📋Context

Most nutrition apps force a choice — a powerful database that's painful to use, or a friendly counter with no depth — and nearly all assume a live connection and a cloud account. Corpus Mio set out to be both deep and private: authoritative USDA nutrition data, a home-pantry model that ties inventory to logging, AI recipe help, and full offline operation, all on infrastructure a single person owns. Logging happens in kitchens, gyms, and grocery aisles where connectivity is unreliable, so offline couldn't be an afterthought — it had to be the foundation.

⚠️Problem

Risk if Unresolved

• Users abandon logging the moment the app fails offline
• Inaccurate or tedious entry erodes trust in the numbers
• Health data sits in a vendor's cloud outside the user's control

🔒Constraints & Requirements

Non-Goals

• Social features (sharing, friends, feeds) — intentionally excluded for privacy
• Multi-day meal planning (single-day logging by design for the MVP)
• Native iOS/Android apps (PWA distribution instead)

🎯Strategy

Decision Rationale

• Offline-first via IndexedDB because logging happens where networks are weak, and a durable, queryable queue is required for correctness.
• Next.js server components and route handlers so API keys (USDA, Anthropic) stay server-side and never enter the client bundle.
• Drizzle ORM for explicit, visible SQL migrations and first-class TypeScript schema over hidden generation.
• Claude (Sonnet) for recipe generation for reliable structured (JSON) output and strong reasoning over dietary constraints.

🚀Execution

Rollout & Risk Controls

• Environment validated at boot via a Zod schema — the process fails fast on misconfiguration
• Invite-gated registration to control access during rollout
• A health endpoint checks database connectivity for monitoring

🏗️Architecture

System Components

• App & API (Next.js 16): server components plus 33 route handlers; secrets stay server-side.
• Data layer (Drizzle + PostgreSQL): 16-table normalized schema with 19 explicit SQL migrations.
• Offline engine (IndexedDB + service worker): durable operation queue, optimistic UI, Background Sync.
• External integrations: USDA FoodData Central (search), Open Food Facts (barcode), Anthropic Claude (recipes).
• Delivery (Caddy + systemd): TLS termination and process supervision on a single Ubuntu host.

Data Flows

• Offline log: mutation queued in IndexedDB → optimistic UI update → Background Sync replays on reconnect → server confirms → operation cleared.
• Food search: pantry → custom foods → cached USDA → live USDA API, caching new results locally on a miss.
• AI recipe: Claude returns ingredients → fuzzy-match to cached foods → fall back to USDA search → fall back to a custom food → user reviews matches and saves with frozen per-serving nutrition.

🛡️Security

Controls Implemented

• Server-only API routes keep USDA and Anthropic keys out of the client bundle
• Session auth via httpOnly iron-session cookies; passwords hashed with bcrypt
• Per-user authorization checks on all data endpoints; invite-gated registration
• Boot-time environment validation (Zod) and per-IP rate limiting on auth routes

⚙️Operations

📊Results

💡Lessons Learned

📦Artifacts

• USDA FoodData Central API
• Open Food Facts
• Anthropic Claude API

Selected Technical Details

                // Offline-first: every mutation is queued, then replayed on reconnect.
export async function queueOperation(op: QueuedOperation) {
  op.tempId ??= crypto.randomUUID();   // dedupe key — survives retries
  await idb.put("pending-operations", { ...op, status: "pending", retryCount: 0 });
  applyOptimisticUpdate(op);            // UI updates immediately
  if (navigator.onLine) void flushQueue();
}

// On sync: 3 attempts with exponential backoff; stop on auth failure.
async function flushQueue() {
  for (const op of await idb.getAll("pending-operations")) {
    const res = await fetch(op.url, { method: op.method, body: JSON.stringify(op.payload) });
    if (res.ok) await idb.delete("pending-operations", op.tempId);
    else if (res.status === 401) break;            // re-auth required
    else await backoff(op);                          // 1s → 2s → 4s, max 3
  }
}