solelog/CLAUDE.md

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.

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.