Compass/common/CLAUDE.md

common

Types and pure utilities shared by web and backend/*. No environment-specific code.

See the root CLAUDE.md for monorepo context.

Import rules (load-bearing)

• web and backend/* import from common/*.
• common never imports from web or backend/*. Doing so breaks tree-shaking and creates cycles in the TS project references.
• Keep package dependencies here minimal. New runtime deps should live in web or backend/* unless both truly need them.

Layout

common/
├── src/
│   ├── api/schema.ts        Zod schema for every endpoint (props + returns + method + authed).
│   │                        The single source of truth for the API contract.
│   ├── supabase/schema.ts   Auto-generated table types (regen via backend/api).
│   ├── user.ts              User / PrivateUser shapes
│   ├── profiles/            Profile-domain types and helpers
│   ├── filters.ts, filters-format.ts   Search filters
│   ├── envs/                Environment constants, prod config
│   ├── logger.ts            debug() — use everywhere instead of console.log
│   ├── util/                Pure utility helpers
│   └── ...
├── messages/                Translation JSON (de.json, fr.json). English is the inline fallback.
└── tests/

Working in here

• Adding an endpoint schema: add an entry to src/api/schema.ts. The handler lives in backend/api/src/ (see the root CLAUDE.md for the full 3-step flow).
• Regenerating Supabase types: run from the API package, output lands here.

  yarn --cwd=backend/api regen-types-dev    # dev DB
  yarn --cwd=backend/api regen-types        # prod DB (rarely needed)
  

• Date / timestamp convention: Date in TS, TIMESTAMPTZ in Postgres, Zod handles the wire serialization. Strings in localStorage need manual conversion back to Date on load.
• Translations: see ../docs/internationalization.md.

Build / test

yarn --cwd=common typecheck
yarn --cwd=common lint[-fix]
yarn --cwd=common test