TypeScript authoring and JavaScript runtime
Edit canonical.ts, .mts and .svelte sources and the owning Tailwind recipe inputs. TypeScript 7 emits ignored .js and .mjs siblings for the native compatibility graph; local development uses that graph. Production uses SvelteKit 3 with adapter-static, compiles authored Svelte components directly and ships the complete assembled artifact from dist/. The browser does not load TypeScript directly. Supporting Kit/checker peers are isolated in tooling/svelte; their TypeScript 6 dependency does not replace the application compiler.
Use Node.js 24. npm ci installs dependencies and compiles through prepare; npm run dev-server, npm test, and the production build/check commands also compile first. With a server already running, compile after source edits before reloading. Direct Node and Playwright commands need the same compilation step.
.js and .mjs specifiers in source imports, dynamic imports, worker URLs, HTML scripts, and runtime commands. For example, import './data.js' in profile.ts resolves to the authored TypeScript for checking and to emitted JavaScript at runtime. Do not edit or commit emitted siblings. Third-party vendor bundles retain their own source formats.
The production and test compiler projects are separate and strict. The app, server, worker, and editor projects also retain their environment-specific safety checks; migration completion does not permit weakened flags or suppression comments. See the app’s source and compiler contract.
Source modules remain the ownership boundary. Regenerate MODULE_MAP.md when modules or imports change. GitHub Actions owns the exhaustive browser and combined-coverage matrix.
Presentation and styling ownership
Svelte components own first-party markup. Readonly presentation projections prepare display data; typed controllers retain domain calculations, storage, requests, navigation and action dispatch. Compose ordinary UI through typed child components. Existing synchronous HTML facades serialize the same owners only at retained native compatibility boundaries. Preserve input identity, drafts, selection, focus and live child hosts through hydration and refresh. Async actions must retain their original profile, request and mounted owner before publishing results. Component disposal releases UI resources; accepted durable writes follow their domain transaction rather than being canceled solely because a view closed. Tailwind utilities and semantic recipes are scoped and prefixed, with no global Preflight. Theme tokens, stylesheet URLs, specificity and cascade positions remain contracts. Necessary native CSS covers tokens, keyframes, vendor integration and reviewed print/report boundaries. See Svelte and Tailwind for source owners and commands.File layout
Entry points
The production route atjs/kit/routes/app/+page.svelte renders the shared AppShell. Its layout hydrates the route before importing the existing main.js service entry. Kit shares one Svelte runtime and owns navigation within #kit-root; links and forms outside that root retain their document handlers.
The native development document retains js/main.js, compiled from js/main.ts. The separate native compatibility build remains available for its own regression checks; it is not the default shipping artifact. npm run production:build assembles the static Kit app in dist/; serve that entire directory. See Deployment.
main.ts installs extension, foundation, cold health/Light loaders, UI shell hooks, and delegated shell actions, then calls startApp() from startup-orchestrator.ts. Startup initializes encryption/storage, active-profile data, maintenance and OAuth callbacks before completing the current route. It awaits initial navigation before declaring data-app-ready and reports failure without replacing unreadable profile data.
Feature loaders retain route- and data-aware loading for health, Light, Chat, import, export, Settings, sharing and EMF. Stable facade, worker and stylesheet URLs remain available where the build verifies their public closure; arbitrary emitted development modules are not a public production module API.
The existing root service worker remains the sole offline/update owner. Kit must not introduce another worker, version poller or competing consent gate. The build retains the legal-consent ordering and CSP without enabling inline executable scripts.
Trusted build-time extension boundary
app-extension-runtime.ts supports one trusted extension selected while composing an edition build. Public and self-hosted builds install the core no-op adapter through app-extension-bootstrap.ts. This is not a runtime plugin marketplace or a mechanism for loading arbitrary remote code.
The contract exposes bounded hooks for Settings and onboarding slots/actions, AI provider ownership/authorization/transport/options/errors, voice request authorization and playback policy, extra sync keys/encrypted prefixes/conflict resolution/post-apply refresh, and startup. An extension must have a stable ID. If an active extension owns an AI request but does not provide a successful authorization hook, the call fails closed before transport.
Marker catalog and placement boundary
The marker catalog uses an authored TypeScript → generated TypeScript → emitted JavaScript chain. Category modules underjs/marker-schema/ are the source of truth, scripts/build-marker-schema.mts generates js/marker-schema.ts, and long-lived consumers continue to use the js/schema.ts compatibility facade through its ./schema.js runtime specifier. This keeps a large catalog maintainable without forcing a broad import-graph refactor.
Marker storage and display are separate boundaries. Profile values and companion metadata remain keyed by native category.markerKey; immutable gb:marker:* and custom:* IDs let marker-placement.ts apply a per-profile visual category only after getActiveData() completes calculations and unit conversion. Renderers may use displayCategoryKey, but mutations must resolve through storageDotKey.
Units follow the same projection rule. unit-profiles.ts maps canonical marker storage into the profile’s International/SI (EU), Australia/New Zealand (ANZ), or US display units after calculation and range resolution. Import review and manual entry convert compatible selected units back to canonical values. Individual renderers must not carry their own regional conversion tables.
The terminology registry follows a separate authoring and generation path. It is optional metadata and is intentionally outside startup, persistence, import/export, backup, sharing, and sync. See Marker model and category placement and Laboratory terminology registry.
Navigation and dashboard IA
The sidebar has three conceptual groups:- Home:
dashboard, the customizable cross-lens overview. - Lenses:
labs,genome,body,light,insight, andrecommendations.views-router.tsvalidates and dispatches these routes. Dashboard route/widget wiring is composed indashboard-view-composition.ts, with the dashboard shell rendered throughdashboard-page-view.ts; lab category routes render throughcategory-page-view.ts; Labs, Genome, Body, Insight, and Recommendations pages are rendered throughlens-pages.ts; shared lens page chrome and ordering live inlens-page-shell.ts; the Light page shell lives inlight-page-view.ts, while channel pills and drill-down panels live inlight-channel-view.ts. - Tools: focused utilities such as compare dates, correlations, knowledge base, custom markers, and EMF assessment entry points.
recommendations route. The page aggregates data-linked recommendation candidates from Labs, Body, Light, and Genome signals, while product option rendering and affiliate disclosure remain owned by recommendations.ts.
Shared health tools and canonical writes
Direct API chat and local CLI chat share the semantic tool runtime and native review boundary. The model can prepare named health-field changes from an exact snapshot; it cannot Apply, control application management, or run arbitrary storage mutations. Provider adapters own transport and capability negotiation. See Health chat tools. Native editors, chat proposals, imports, and Sync must preserve canonical profile-data ownership.profile-data-writes.ts rebases a caller’s named changes against persisted state and retains unrelated newer fields. Sync planners preserve observed versions and deterministic conflict order. A full object captured before an await is not permission to overwrite later data.
Optional PDF feed discovery stays in its leaf model and runtime controller, then enters the existing reviewed import workflow. Method-specific body measurements use manual-reading persistence. Personal marker baselines are derived chart/context data, not mutable healthy ranges. See Report-source internals, Sync internals, and Lab marker internals.
Dependency direction
npm run architecture:check enforces zero cycle ceilings and the repository’s explicit boundary rules. The architecture contract owns these rules; the generated module map records actual imports. The module reference groups ownership areas rather than defining a second set of layer restrictions.
External dependencies
Bundled locally undervendor/:
AI providers, Custom API, Local AI, xAI voice, and ElevenLabs voice are called directly from the browser. The dedicated compatibility service receives only policy-classified wearable, CAMS, NRAS, and credential-free public-page operations; it must never become a generic AI/voice proxy. The dedicated share service receives only browser-encrypted envelopes and metadata. Independent self-hosts keep their own same-origin compatibility endpoints.