65 lines
4.5 KiB
Markdown
65 lines
4.5 KiB
Markdown
# 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.
|