Code Quality & Maintainability

A second engineer modifying coach-chat context-loading, meal-analysis JSON parsing, biometric calculations, blueprint generation, or any of the 100 server modules has no automated way to know whether their change broke existing behavior. With AI-generated outputs in critical paths and no contract tests on parseAiToolCall-style helpers, even silent regressions in the AI gateway response shape go undetected.

Every change ships untested. Two-engineer team velocity will collapse the first time a refactor breaks a downstream coach prompt path, because there is no safety net to catch it before users see broken state. In a health-adjacent product, an undetected regression in biometric calculation or coach safety filtering becomes an end-user incident, not a CI failure.

There is one automated test in the entire codebase. Everything else has been verified only by you clicking through the app. The first time someone else changes the code, there is no machine to tell them whether they broke something -- they will have to test by hand, every time, and they will miss things.

Add a test script in package.json (vitest run). Then prioritize tests for the highest-risk pure functions first: parseAiToolCall in meal-analysis.ts, the safety-filter helpers in _shared/safety-check.ts / medical-safety.ts / mental-health-risk.ts, the longevity-score composition in useDashboardData, and the region inference already covered. Target: 30 unit tests covering pure server-side helpers within the first sprint; defer integration / E2E to later.

L — 1–2 weeks

• vitest.config.ts
• package.json:6-13

TanStack Query is a transitive devDep of TanStack Start but is treated by this codebase as if it didn't exist. Cache invalidation, request deduplication, automatic refetch on focus, optimistic updates, and stale-while-revalidate are all reimplemented (badly) via useEffect + ad-hoc invalidation buses (lib/data-events.ts, data-invalidation-bus.ts) -- or simply not implemented, which is why the dashboard reloads everything on every render path.

Manual data layer is a maintenance tax on every component. Each one redeclares loading + error + retry + invalidation state by hand. A second engineer cannot rely on a consistent data-fetching idiom and will introduce subtle bugs every time they add a new query.

A standard tool for fetching and caching data in React is already installed in your project, but the project does not actually use it. Instead, every screen re-implements the same fetch / loading / error pattern by hand. That is why simple data changes (like logging a meal) sometimes don't immediately appear elsewhere in the app -- there is no shared cache.

Either remove @tanstack/react-query from package.json to avoid shipping unused code, OR (better) adopt it: wrap the app in a single QueryClientProvider, migrate the top 5 data-fetching hooks (useProfile, useDashboardData, useLifestyleData, useBodyMeasurements, useWorkoutLogs) to useQuery, and let the rest follow. Choose one direction -- do not leave the library installed but unused.

M — 1–3 days

• package.json:49
• src/hooks/useDashboardData.ts
• src/components/CoachPage.tsx

Files this large in a codebase with no tests (cross-ref COD-001) become a no-go zone: a second engineer cannot safely change anything without reading 2,000 lines of context. Several of these (CoachPage, JournalPage, training routes) are page components that should be thin layouts composing extracted hooks and sub-components.

Onboarding cost for a second engineer is dominated by these five files. Bug-fix turnaround time on the coach surface -- the product's main feature -- will be 3-5x slower than on a properly factored codebase because any change requires re-reading the whole file.

Five files in your app are each 700-2,100 lines long and try to do everything in one place: drawing the screen, fetching data, running business logic, talking to Supabase. The largest one is your coach page. A new developer would need a full day just to safely add a button to this page.

1. data-fetching into hooks in src/hooks/, (.
2. sub-sections into child components, (.
3. pure helpers into src/lib/. Target <=300 LOC per component file and <=100 LOC per function. Start with CoachPage.tsx -- extract useCoachIntakeFlow, useCoachChatState, and a CoachPersonaPanel sub-component.

L — 1–2 weeks

• src/components/CoachPage.tsx
• src/routes/api.coach-chat.ts
• src/components/CoachChatSheet.tsx

The dominant error-handling idiom is: try { ... } catch (e) { console.warn(e); return null }. Callers receive a null and have no way to distinguish no-data-found from AI-gateway-threw from Supabase-RLS-denied from network-blew-up. In a Cloudflare Worker without an error tracker, those console.warn lines never reach a human.

Production failures become invisible. The coach silently degrades, the bio-twin avatar silently skips, the north-star quietly returns null -- and the user sees a UI that just does not work right without anyone knowing why. The team will only learn about failures through user complaints, weeks later.

When something goes wrong in the app, the code mostly just writes a note to a log nobody reads and pretends everything is fine. Combined with the lack of an error-tracking service, this means failures in production are essentially invisible until a user complains.

1. catch only what you can handle; let everything else bubble; (.
2. every catch either rethrows, returns a typed Result type, or reports to an error tracker -- never just console.warn + return null; (.
3. for fire-and-forget calls, name them: .catch(reportNonFatal). Pair this fix with installing Sentry (OPS-005).

M — 1–3 days

• src/server/_shared/ai-tool-call.ts
• src/server/north-star.functions.ts
• src/server/bio-twin-active.ts

Voice coach and text coach are the same conversation pipeline with a different transport. They should share a single buildCoachContext / streamCoachReply core. As written, every time a context loader is added (e.g. new safety filter) the team must remember to wire it in both routes, and they will forget.

Bug fixes drift between the two surfaces. A safety filter added to text-coach will not protect voice-coach users until someone notices the omission. In a mental-health-adjacent product (cross-ref DOM-007), that drift is a domain-compliance risk in addition to a code-quality one.

Your text coach and voice coach are mostly the same code copied into two files. When you fix a bug in one, you have to remember to fix it in the other. Sooner or later someone will forget, and one of the two coaches will behave differently from the other.

1. stays in the route file; everything downstream of messages lives in the shared module.

M — 1–3 days

• src/routes/api.coach-chat.ts
• src/routes/api.voice-coach-chat.ts

Most server functions trust their input shape based on TypeScript types that the runtime cannot enforce. A malformed client request -- or a deliberately crafted one -- can pass right through into Supabase queries and AI prompts. Cross-ref SEC-010 frames this as a security finding; here it is also a maintainability finding because callers cannot read a schema to know what each function accepts.

Every change to a server function expected input shape is a runtime gamble: TypeScript will not catch a mismatch from the client, only the eventual database error will. In a codebase with no error tracker (OPS-005) and no tests (COD-001), that means the only signal of contract drift is a user-visible failure.

When the app backend receives data from the browser, it mostly trusts the data is shaped correctly without checking. If anything ever sends a slightly wrong shape -- a bug, a stale cached client, a malicious user -- the failure will happen deep inside the database or the AI call instead of being caught at the front door.

Zod is already in dependencies (zod ^3.24.2). Add a one-screen schema at the top of each server function and parse the input through it before any business logic. Start with the highest-risk endpoints (api.coach-chat.ts, api.voice-coach-chat.ts, body-measurements, meal-analysis). Use zod safeParse so validation failures return a clean 400, not a thrown 500.

M — 1–3 days

• src/routes/api.coach-chat.ts
• src/routes/api.voice-coach-chat.ts
• src/server/

The shadcn/ui registry was added wholesale (typical Lovable scaffolding) rather than per-component. Because the app declares sideEffects: false in package.json, tree-shaking probably eliminates most of these from the production bundle -- but the source files still bloat the repo, slow grep and IDE indexing, and tempt future developers to import unused primitives.

Repo size and search noise. Not a launch blocker -- tree-shaking probably handles the runtime cost -- but a steady tax on every grep and every code review. Cleaning it up signals discipline to a second engineer.

Three quarters of the UI building blocks shipped in your project are never used anywhere. They were added by the scaffolding tool, not by anyone who needed them. They make the codebase look bigger than it is, but they do not run.

Delete the 36 unused .tsx files from src/components/ui/. When a future feature needs one, re-add it via npx shadcn add. Keep the 10 that are imported. Verify bun run build still succeeds.

S — under ½ day

• src/components/ui/
• src/components/ui/sidebar.tsx

This is half-implemented. The sparklines render and look real to the user, but six of every seven points are fabricated. A user comparing their dashboard to a friend would see identical history for the first six days. In a longevity-claim context (cross-ref DOM-006), showing fabricated trend data is an evidence-quality issue, not just a code TODO.

Users see a polished-looking trend chart that is partly fictional. In a health-adjacent product where data integrity is a feature, that is a credibility risk. The TODO has been in place long enough that the team has stopped seeing it.

Your dashboard shows mini line charts for HRV, recovery, strain, and sleep over the last seven days. Right now, six of the seven days are made-up numbers and only the most recent day reflects real data. The TODO comment in the code shows this was a stopgap that did not get finished.

Either implement the real 7-day aggregation (a single Supabase query over biometrics joined to user_id with a 7-day window, ordered ascending), or render the sparkline only when 2+ real points exist and otherwise show a collecting-data state. Do not ship synthetic history as if it were real.

S — under ½ day

• src/hooks/useDashboardData.ts:493-507

react-hooks/exhaustive-deps exists because missing deps cause stale-closure bugs: the effect captures an old value, never re-runs when it should, and produces hard-to-debug bugs. Disabling the rule one occurrence at a time is the dominant idiom in this codebase -- 28 disables in 86,000 LOC indicates a systematic give-up rather than isolated false positives.

Each disable is a latent stale-closure bug waiting for the right interaction sequence. A second engineer touching any of these effects will not know which disables are intentional (genuinely correct to omit deps) and which are I-gave-up. Combined with no tests (COD-001), reverting a wrong disable will silently break things.

React has a linter rule that catches a common bug pattern. The code disables this rule 28 times. Each disable is a place where the original developer knew about a potential bug but chose to silence the warning instead of fixing it. The next developer will not know which of those silences are safe.

Treat each disable as a small refactor: replace useEffect + disabled deps with useEffectEvent (React 19 has it) or extract the changing value into a ref. For event-handler-style effects, use useEffectEvent. Aim to halve the count in the first sprint and reach zero within two sprints.

M — 1–3 days

• src/components/CoachPage.tsx:493,1106,1112,1125,1161,1245
• src/components/CoachChatDialog.tsx:86

On Cloudflare Workers, console.* writes go to the Worker tail log, which is ephemeral and not searchable beyond a short retention window without wrangler tail running. There is no level filtering, no PII redaction, and no structured fields. Combined with COD-004 (catch-and-console as the error-handling idiom), this guarantees that production failures are visible only if someone is actively tailing logs at the moment of failure.

Logs are practically useless for diagnosing production issues. When a user reports the-coach-gave-me-a-weird-response-yesterday, there is no log to look up. The Lovable AI Gateway costs (cross-ref AI-003, AI-006) cannot be reconciled against in-app actions because there is no per-call log.

The app developers leaned heavily on console.log statements when debugging -- there are 177 of them. They print to Cloudflare short-lived log stream and then vanish. There is no central log that someone could read later to figure out why something went wrong yesterday.

1. so logs survive longer than a Worker invocation.

M — 1–3 days

• src/server/bio-twin-avatar.ts
• src/components/CoachPage.tsx
• eslint.config.js

The shadcn scaffolding introduced use-mobile.tsx with a different naming convention than the rest of the hooks directory. A trivial inconsistency on its own, but symptomatic of generator output being merged without normalisation.

Negligible on its own -- a tiny papercut for IDE auto-complete and for grep-by-convention. Mentioned for completeness so the team can decide whether to enforce a hook-naming lint rule.

One hook in your project is named use-mobile with a dash. Every other hook is named useSomething without a dash. This is a small inconsistency left over from the scaffolding tool -- easy to fix, low priority.

Rename src/hooks/use-mobile.tsx to src/hooks/useMobile.tsx (and update its one importer). Optionally add an ESLint custom rule or eslint-plugin-filename-rules to enforce useCamelCase.tsx for hook files.

S — under ½ day

• src/hooks/use-mobile.tsx
• src/hooks/

Three guard rails for dead-code prevention are disabled at the configuration level. The codebase has no tool actively telling the team this-import-is-unused. Combined with the 36 unused shadcn primitives (COD-006), this signals that dead-code accumulation is unobserved.

Dead imports and dead variables drift in unnoticed. Each one is small; together they make grep noisier and increase the surface area a second engineer must read. Low-severity, but the fix is a one-line config change.

Your linter is told to ignore unused variables and imports. So if a developer leaves dead code in a file, no tool will warn about it. The cleanup is automatic -- turn the rule on, fix what it finds.

Change eslint.config.js:24 to @typescript-eslint/no-unused-vars at warn level with an argsIgnorePattern of ^_, and set tsconfig.json noUnusedLocals: true and noUnusedParameters: true. Run bun run lint and bun run build; fix what they flag.

S — under ½ day

• eslint.config.js:24
• tsconfig.json:19-20