bas/solelog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: correct CLAUDE.md after reverse-engineering apps/web backend

Browse Source 
The backend is not remote: apps/web is a Next.js 16 app with the API
routes, better-auth, and a Neon Postgres data layer. Document the data
model, the mobile<->web API contract, and the missing /api/logs route.
This commit is contained in:
Bas van Rossem
2026-06-17 10:22:20 +02:00
parent d94d0b188b
commit 9ca8a454f4
1 changed files with 63 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
CLAUDE.md
View File

@@ -4,48 +4,86 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## What this is ## What this is
A cross-platform (iOS / Android / web) **time-tracking app for insole (orthotics) production**, built on the **"Create" / Anything AI** platform and exported to run locally. The UI is in **Dutch**. The user picks an insole type (`Type zool`: Kurk / Berk / 3D), a handling/task (`Type handeling`), and a count (`Aantal zolen`, default 2), then runs a stopwatch (start / pause / stop & save / double-press discard). History is exportable to CSV (nl-BE locale, `HH:MM:SS` durations); the Settings tab manages handelingen per zooltype. A **time-tracking app for insole (orthotics) production**, built on the **"Create" / Anything AI** platform and exported to run locally. The UI is in **Dutch**. A worker picks an insole type (`Type zool`: Kurk / Berk / 3D), a handling/task (`Type handeling`), and a count (`Aantal zolen`, default 2), then runs a stopwatch (start / pause / stop & save / double-press discard). The History tab lists past sessions and exports CSV; the Settings tab manages handelingen per zooltype.
**This repo is frontend-only.** The backend API routes (`/api/tasks`, `/api/logs`) and the database (`production_tasks`, `time_logs` tables) live on the remote Create web app, reached via `EXPO_PUBLIC_BASE_URL` (see `apps/mobile/.env`). Editing tasks/history happens against that remote DB, not in this code. It is a **two-app monorepo, not frontend-only** — the backend lives in `apps/web`:
- **`apps/mobile`** — the Expo Router app (iOS / Android / web client). This is what the user runs on their phone via Expo Go / EAS builds.
- **`apps/web`** — a **Next.js 16** app that serves the backend HTTP API (`/api/*`), authentication, and a near-empty web UI. The mobile app talks to it over `EXPO_PUBLIC_BASE_URL`. In production it is the deployed `*.created.app` site.
The database is **Neon serverless Postgres**, reached only from `apps/web` via `DATABASE_URL`.
## Layout ## Layout
- Yarn 4 (Berry) monorepo, `node-modules` linker. Workspaces = `apps/*`; only **`apps/mobile`** (the Expo app) exists. Yarn 4 (Berry) monorepo, `node-modules` linker. Workspaces = `apps/*` → **`apps/mobile`** and **`apps/web`**.
- **`publisher/`** is NOT a workspace — it's a standalone OpenNext + AWS S3 tool (its own `yarn.lock`) for building/deploying the Next.js *web* side. Rarely touched.
- **`publisher/`** is NOT a workspace — it's a standalone OpenNext + AWS S3 tool (its own `yarn.lock`) for building/deploying `apps/web`. Rarely touched.
## Backend: API + data model
API routes live in `apps/web/src/app/api/`. The DB layer is `apps/web/src/app/api/utils/sql.ts` — a Neon tagged-template `sql\`...\`` (parameterised; interpolations are bind params, not string concatenation). Auth is **better-auth** (`apps/web/src/lib/auth.ts`): cookie sessions for web, `Authorization: Bearer <token>` for mobile (token from `/api/auth/token`).
Schema, reverse-engineered from the queries (no migrations file ships in the repo):
- **`production_tasks`** — `id`, `name`, `insole_types text[]` (subset of `Kurk` / `Berk` / `3D`)
- **`time_logs`** — `id`, `task_id` (FK → production_tasks), `start_time`, `end_time`, `duration_seconds`, `pair_count`, `insole_type`, `notes`
API surface the **mobile app expects** vs what `apps/web` **provides**:
| Endpoint | Method | Used by mobile | Exists in apps/web |
|---|---|---|---|
| `/api/tasks` | GET, POST | yes | ✅ `api/tasks/route.ts` |
| `/api/tasks/:id` | PUT, DELETE | yes | ✅ `api/tasks/[id]/route.ts` |
| `/api/logs` | GET, POST | yes | ❌ **MISSING** |
| `/api/export` | GET (CSV) | yes | ✅ `api/export/route.ts` |
| `/api/session`, `/api/auth/*` | — | (auth plumbing) | ✅ |
### ⚠ Known gap: `/api/logs` is missing
The mobile app reads the History list (`GET /api/logs`) and saves a finished session (`POST /api/logs`), but **no such route exists in `apps/web`** — only the CSV `/api/export`. Against this local backend, Stop & Save and the History tab 404. (The deployed `*.created.app` instance presumably has it; it just wasn't in this export.) Contract to rebuild it from the callers:
- `POST /api/logs` body: `{ task_id, start_time (ISO), end_time (ISO), duration_seconds, pair_count, insole_type }`
- `GET /api/logs` returns an array of `{ id, task_name (join on production_tasks.name), start_time, duration_seconds, pair_count, insole_type }`, and (for parity with export) ideally `end_time`, ordered by `start_time`.
## Commands ## Commands
Run from the repo root unless noted. There are no `start`/`lint`/`test` npm scripts — invoke the tools directly. Run from the repo root unless noted. The root has **no** `start`/`lint`/`test` scripts — invoke the tools directly.
```bash ```bash
yarn install # install (Yarn 4) yarn install # install everything (Yarn 4)
npx oxlint # lint (config: .oxlintrc.json) — this is the real linter npx oxlint # lint (config: .oxlintrc.json) — the real linter
npx oxfmt # format (config: .oxfmtrc.json) — 2-space, single-quote, semi, width 100 npx oxfmt # format (config: .oxfmtrc.json) — 2-space, single-quote, semi, width 100
cd apps/mobile # Mobile (apps/mobile)
npx expo start # dev server; press a/i/w or scan the QR with Expo Go cd apps/mobile && npx expo start # dev server; press a/i/w or scan QR with Expo Go
npx expo start --web # web target only cd apps/mobile && npx expo start --web # web target only
npx tsc --noEmit # typecheck (strict; @/* -> src/*) cd apps/mobile && npx tsc --noEmit # typecheck (strict; @/* -> src/*)
yarn jest # all tests (jest-expo preset) cd apps/mobile && yarn jest # tests (jest-expo); add a path or -t "name" for one
yarn jest src/utils/iap/__tests__/useInAppPurchase.test.ts # single file cd apps/mobile && eas build --profile <development|preview|production> --platform <android|ios>
yarn jest -t "name" # single test by name
eas build --profile <development|preview|production> --platform <android|ios> # native builds (eas.json) # Web / backend (apps/web)
cd apps/web && yarn dev # Next.js dev on http://localhost:4000
cd apps/web && yarn build # next build (publisher wraps this for deploy)
cd apps/web && yarn typecheck # tsc --noEmit (next.config.js ignores TS errors at build time!)
cd apps/web && npx vitest # tests (vitest + jsdom)
``` ```
> `eslint` / `typescript-eslint` are in devDeps but there is **no eslint config** in the tree — use **oxlint**, not eslint. > `eslint` / `typescript-eslint` are in devDeps but there is **no eslint config** in the tree — use **oxlint**, not eslint.
## Architecture (the parts that span files) ## Environment
- **Routing:** Expo Router, file-based under `apps/mobile/src/app/`. `_layout.tsx` is the root: it gates render on `useAuth().initiate()` + `isReady` (loads the persisted session before showing anything) and provides the React Query client. `(tabs)/` holds the three screens — `index.tsx` (Stopwatch), `history.tsx` (Geschiedenis), `tasks.tsx` (Instellingen). Secrets are gitignored (`.env`). Mobile env is `apps/mobile/.env` (`EXPO_PUBLIC_*`): `EXPO_PUBLIC_BASE_URL` points the client at the web backend; `EXPO_PUBLIC_PROJECT_GROUP_ID`/`HOST` feed the patched global fetch. Web needs `DATABASE_URL` (Neon), plus `BETTER_AUTH_URL` and the trusted-origin URLs for auth. `EXPO_PUBLIC_CREATE_ENV` (`PRODUCTION`/`DEVELOPMENT`) + `__DEV__` gate analytics, Sentry, the in-app "anything-menu", and dev-only native module stubs.
- **Platform vs web entry points are split by file extension.** Native: `index.tsx` → `entrypoint.ts` → `App.tsx`. Web: `index.web.tsx` → `App.web.tsx`. The `.web.*` files add sandbox-iframe plumbing (postMessage handshake, navigation sync, screenshot capture, healthcheck) used by the Create preview panel — this is why the web root looks very different from the native one.
- **Global `fetch` is monkey-patched.** `src/__create/polyfills.ts` replaces `global.fetch` with `src/__create/fetch.ts`, which rewrites first-party (`/...`) URLs onto `EXPO_PUBLIC_BASE_URL`, injects project/host headers, and attaches the SecureStore JWT. App code calls `fetch('/api/...')` and relies on this. For explicit auth, `src/utils/auth/getSession.ts` exposes `authFetch` (better-auth bearer JWT). ## Architecture notes (mobile)
- **Web support is achieved via Metro module aliasing**, not separate web code. `apps/mobile/metro.config.js` `resolveRequest` swaps a large set of native modules for stubs in `polyfills/web/` when `platform === 'web'` (and a few in `polyfills/native/`, plus dev-only stubs like `react-native-purchases` outside production). **Consequence: adding a native dependency that gets imported on web requires adding a web polyfill alias here, or the web build breaks.**
- **Styling:** NativeWind/Tailwind config extends `@anythingai/app/tailwind.config`, but the screens themselves mostly use React Native `StyleSheet`/inline styles. Inter is the font. - **Routing:** Expo Router, file-based under `apps/mobile/src/app/`. `_layout.tsx` gates render on `useAuth().initiate()` + `isReady` (loads the persisted session first) and provides the React Query client. `(tabs)/` holds `index.tsx` (Stopwatch), `history.tsx` (Geschiedenis), `tasks.tsx` (Instellingen).
- **Environment gating:** `EXPO_PUBLIC_CREATE_ENV` (`PRODUCTION` / `DEVELOPMENT`) and `__DEV__` gate analytics, Sentry, the in-app "anything-menu", and dev-only native aliases. Real native SDKs only load in production builds. - **Entry points split by extension.** Native: `index.tsx` → `entrypoint.ts` → `App.tsx`. Web: `index.web.tsx` → `App.web.tsx` (adds the Create sandbox-iframe plumbing — postMessage handshake, navigation sync, screenshot, healthcheck).
- **Global `fetch` is monkey-patched.** `src/__create/polyfills.ts` swaps `global.fetch` for `src/__create/fetch.ts`, which rewrites first-party (`/api/...`) URLs onto `EXPO_PUBLIC_BASE_URL`, injects project/host headers, and attaches the SecureStore JWT. App code calls `fetch('/api/...')` and relies on this.
- **Web support is Metro module aliasing**, not separate code. `apps/mobile/metro.config.js` `resolveRequest` swaps many native modules for stubs in `polyfills/web/` when `platform === 'web'`. **Adding a native dependency imported on web requires a web polyfill alias here, or the web build breaks.**
- **Styling:** NativeWind/Tailwind config extends `@anythingai/app/tailwind.config`, but screens mostly use React Native `StyleSheet`/inline styles. Inter font.
## Conventions & gotchas ## Conventions & gotchas
- **Do not edit platform-managed files.** Files under `apps/mobile/__create/` and `apps/mobile/src/__create/`, and the auth files in `src/utils/auth/` (`useAuth.ts`, `getSession.ts`, etc.), carry `⚠ ANYTHING PLATFORM — DO NOT REWRITE` headers. They define the public auth surface (`signIn`/`signUp`/`signOut`/`auth`/`isAuthenticated`/`isReady`) and the fetch/sandbox plumbing; rewriting them breaks auth or the Create preview. `src/app/_layout.tsx` is editable except for the `<AuthModal />` render and the `initiate()` + `isReady` gate. - **Do not edit platform-managed files.** Files under `apps/mobile/__create/` and `apps/mobile/src/__create/`, the auth files in `apps/mobile/src/utils/auth/`, and `apps/web/src/lib/auth.ts` carry `⚠ ANYTHING PLATFORM — DO NOT REWRITE` headers. They define the auth surface (`signIn`/`signUp`/`signOut`/`auth`/`isAuthenticated`/`isReady`), the fetch/sandbox plumbing, and the better-auth config (bearer plugin, name backfill, trusted origins, `sameSite:'none'` cookies). Rewriting them breaks auth or the Create preview. `apps/mobile/src/app/_layout.tsx` is editable except the `<AuthModal />` render and the `initiate()` + `isReady` gate.
- **Do not bump patched dependencies.** `react-native`, `expo-router`, `expo-store-review`, `react-native-purchases(-ui)`, `@expo/cli`, `@react-native-community/netinfo`, and others use `patch:` entries in `package.json` backed by `.yarn/patches/`, pinned further by root `resolutions`/`overrides`. Upgrading them discards the patch and breaks the app. When running `npx expo install --fix`, skip any package marked `patch:`. - **Do not bump patched dependencies.** `react-native`, `expo-router`, `expo-store-review`, `react-native-purchases(-ui)`, `@expo/cli`, `@react-native-community/netinfo`, etc. use `patch:` entries backed by `.yarn/patches/`, pinned further by root `resolutions`/`overrides`. Upgrading discards the patch. When running `npx expo install --fix`, skip any `patch:` package.
- This is an exported template: package versions are pinned exact (no `^`) deliberately. Prefer minimal, targeted changes. - This is an exported template: versions are pinned exact (no `^`) deliberately; prefer minimal, targeted changes.