Fieldnote

The original FODMAP app was one HTML file — source of truth and customer deliverable at the same time. Editing it with Claude Code kept producing rewrites, not edits. The fix was to put the complexity in the right place: an explicit build step.

"A build step puts complexity in the right place — explicit and controlled rather than implicit and fragile."

The new shape: src/[app]/ folders with one concern per file (db, parser, lib, state, ui-log, ui-history, ui-insights, ui-settings). A build script reads template.html with {{PLACEHOLDERS}}, injects each file in a known order, writes a single dist/<app>-vX.X.XX.html that's identical to today's customer deliverable.

Behavioural result: AI edits are now surgical. Database changes happen in db.js without touching UI. Demo data lives outside the app build and never accidentally ships to customers. Each file under ~500 lines so the full context fits comfortably in a single AI conversation.

Once a second app (Menopause Companion) was on the horizon, every concept either lived in shared/ once or was app-specific. The principles, lifted from the architecture spec:

• Shared code lives once. No duplication across apps.
• Apps own their schemas. Data structure is app-specific.
• Standard build order. Every app uses the same injection sequence.
• CSS tokens, not values. Shared components consume CSS variables; apps define the values. Zero changes to shared CSS per new app.
• Config-driven components. UI takes config objects. No app-specific logic inside shared components.
• Food DB: identity in shared, condition layers in app. Pure food identity (name, macros, aliases) is shared. FODMAP levels, trigger evidence, histamine ratings live in each app's db.js.

Adding a third app means creating a new src/[app]/ folder. No edits to shared code.

The PWA had to also be a real iOS app — App Store presence matters for trust, even if everything else is browser-first. Capacitor 6 wraps the same single-file HTML in a WKWebView shell.

Storage was the hard part. localStorage is volatile under iOS WKWebView; data needs to survive app kill and reinstall. The fix: a createStore() factory in shared/storage-lib.js that detects the Capacitor runtime at startup and routes reads/writes through @capacitor/preferences (UserDefaults) on iOS, falling back to localStorage on web. All store.* methods became async.

Native polish followed: position:fixed header behind the Dynamic Island, env(safe-area-inset-*) on every sticky element, native <input type="time"> instead of a custom picker, navigator.share({files:[...]}) for backup export, full-width toasts above the bottom tab bar, momentum scrolling.

The marketing site runs full working apps inline, pre-loaded with 31 days of realistic data. The demo dataset is its own spec: not a stripped-down sample but a coherent 31-day arc that produces meaningful Insights and a sensible Report on first view. demo-data.js is a build-time injection — never shipped to customers, always present on fieldnote.health/demo/*.

Side effect: writing the demo data is the strongest UX check you can do. If the data doesn't produce a story across 31 days, the Insights tab probably has the wrong axes.

The point of an AI-paired workflow isn't that the AI is in charge. The point is to push the boring work into a system so the substantive decisions get more attention. On Fieldnote those decisions were:

• The FODMAP database. Monash's public dataset has gaps and ambiguities for ingredient-level use (the canonical use case is per-meal serving size). Remediating that for actual home cooking — what counts as a serving of "garlic", whether "spring onion green" is the same as "spring onion white", how to handle blends — was 40+ hours of hand-curation. No AI shortcut.
• Consumer copy. "Hot flashes" not "vasomotor symptoms". "Doctor-ready report" not "clinical export." Every screen of every product had this pass. AI drafted, the brand voice cut.
• Brand direction. Cream-on-warm-paper palette, slab serif wordmark, illustration-led packaging on Etsy. Quiet, deliberate, doesn't look like another health app.
• Pricing. $12 lifetime. Not $4/month, not $79/year. The number that pays for the design without insulting the user. AI doesn't have an opinion on this; the founder does.

"Each tool is a single file that runs in your browser. Your data is stored on your device. Buy it once. You own it."