mirror of
https://github.com/CompassConnections/Compass.git
synced 2026-07-31 18:28:47 -04:00
54 lines
2.1 KiB
Markdown
54 lines
2.1 KiB
Markdown
# common
|
|
|
|
Types and pure utilities shared by `web` and `backend/*`. No environment-specific code.
|
|
|
|
See the [root CLAUDE.md](../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](../CLAUDE.md) for the full 3-step flow).
|
|
- **Regenerating Supabase types**: run from the API package, output lands here.
|
|
```bash
|
|
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`](../docs/internationalization.md).
|
|
|
|
## Build / test
|
|
|
|
```bash
|
|
yarn --cwd=common typecheck
|
|
yarn --cwd=common lint[-fix]
|
|
yarn --cwd=common test
|
|
```
|