# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

**SoleLog** — a greenfield backend for an **insole (orthotics) production time-tracking system**. Workers time the handling/activities they perform per insole type (`Type zool`: Kurk / Berk / 3D), with the backend as the source of truth. The UI is in **Dutch**, but no client ships yet — the planned mobile (Expo) and admin (Vite + React) clients are described in `docs/roadmap.md`.

The repo currently contains **only the backend service** (`apps/api`) and the shared contracts package (`packages/shared`). It is a clean, dependency-light rebuild.

> Historical note: this repo began as an export from the **Create / Anything AI** platform (a two-app Expo + Next.js monorepo on Neon Postgres). That legacy code (`apps/mobile`, `apps/web`, `publisher/`) was removed in a full cleanup on 2026-06-17 — preserved in git history and summarised in `docs/reference/`.

## Layout

Yarn 4 (Berry) monorepo, `node-modules` linker. Workspaces = `apps/*` + `packages/*`.

- **`apps/api`** — the backend service: **Hono** HTTP server + **better-auth** + **Drizzle ORM** over **libsql/SQLite**.
- **`packages/shared`** — `@solelog/shared`: TypeScript types + **zod** schemas that form the API contracts (e.g. `HealthResponse`, `MeResponse`, `PublicUser`).
- Future clients (`apps/mobile`, `apps/admin`) are planned per the roadmap but not yet present.

## Backend (`apps/api`)

- **App factory.** `src/app.ts` exports `createApp(): Hono`. It mounts the health route, the better-auth handler at `POST|GET /api/auth/*`, and the protected `me` route. `src/index.ts` serves it via `@hono/node-server` on `env.PORT` (default 3000).
- **Routes.**
  - `GET /health` — liveness, returns `{ status: 'ok' }` (`src/routes/health.ts`).
  - `/api/auth/*` — better-auth (email+password, `bearer()` plugin for token auth) (`src/auth.ts`).
  - `GET /api/me` — protected; reads the session via `auth.api.getSession()` and returns `{ user: { id, email, name } }`, else 401 (`src/routes/me.ts`).
- **Auth.** `src/auth.ts` configures better-auth with the Drizzle SQLite adapter, email+password (no email verification), and the bearer plugin so mobile clients can send `Authorization: Bearer <token>`.
- **Database.** `@libsql/client` + `drizzle-orm/libsql`. `src/db/client.ts` opens the connection from `env.DATABASE_URL`; `src/db/schema.ts` holds the better-auth core tables (`user`, `session`, `account`, `verification`) — generated by the better-auth CLI, do not hand-edit. Migrations live in `apps/api/drizzle/`, generated by **drizzle-kit** (`db:generate`) and applied by `runMigrations()` in `src/db/migrate.ts` (`db:migrate`, also runnable directly via `tsx`).
- **Config.** `src/env.ts` reads `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `PORT` from the environment with dev-friendly defaults. See `apps/api/.env.example`.

The planned domain model (users / workbenches / activities / work-sessions) is **not yet implemented** — only the better-auth tables exist. The model and phased plan live in `docs/roadmap.md`.

## Commands

Run from the repo root unless noted.

```bash
yarn install                                   # install everything (Yarn 4)

# Backend (@solelog/api)
yarn workspace @solelog/api dev                # tsx watch — dev server (default :3000)
yarn workspace @solelog/api start              # tsx — run once
yarn workspace @solelog/api test               # vitest run
yarn workspace @solelog/api typecheck          # tsc --noEmit
yarn workspace @solelog/api db:generate        # drizzle-kit generate (new migration from schema)
yarn workspace @solelog/api db:migrate         # apply migrations (tsx src/db/migrate.ts)

# Lint / format (root)
npx oxlint                                     # lint (config: .oxlintrc.json)
npx oxfmt                                      # format (config: .oxfmtrc.json) — 2-space, single-quote, semi, width 100

# Docker (whole stack)
docker compose up --build                      # build + run the api container; health: curl http://localhost:3000/health
```

> Use **oxlint**, not eslint — there is no eslint config in the tree.

## Docs

- **`docs/roadmap.md`** — vision, decisions, architecture, data model, and the phased roadmap.
- **`docs/plans/`** — per-phase implementation plans (e.g. `phase-0-foundation.md`).
- **`docs/reference/`** — reference extracted from the legacy Create/Anything export before cleanup (legacy backend, mobile app, lessons & gotchas).
- **`docs/sessions/`** — dated session logs.