Compass/backend/shared/CLAUDE.md

backend/shared

Backend-only utilities used by backend/api, backend/scripts, and backend/email. Things that need Node-only deps (pg-promise, firebase-admin, monitoring SDKs) but are reused across backends.

See the root CLAUDE.md for monorepo context.

Import rules

• Anything under backend/* may import from here.
• This package never imports from backend/api, backend/scripts, or backend/email. Cross-cutting code lives here; package-specific code stays in its package.
• It may import from common/*.

Layout

backend/shared/src/
├── supabase/
│   ├── init.ts             createSupabaseDirectClient() — pg-promise client (backend SQL)
│   ├── utils.ts            insert / update / updateData / bulkUpsert / bulkUpdate helpers
│   ├── sql-builder.ts      renderSql / select / from / where / orderBy / limit (sanitized)
│   ├── users.ts, messages.ts, notifications.ts, options.ts   Domain queries
├── websockets/
│   ├── server.ts, switchboard.ts
│   └── helpers.ts          broadcastUpdatedUser, broadcastUpdatedPrivateUser, ...
│                           (topics here are what the web `useApiSubscription` listens to)
├── monitoring/
│   ├── log.ts              log.info / log.error — use everywhere on the backend
│   ├── metrics.ts, metric-writer.ts, context.ts, instance-info.ts
├── init-admin.ts           Firebase Admin init
├── encryption.ts           Message encryption helpers
├── analytics.ts, audit-events.ts
└── profiles/, compatibility/, helpers/

Conventions

• SQL: never string-concatenate. Use the helpers in supabase/utils for inserts/updates, or compose with sql-builder for reads. Lowercase SQL by convention.
• New websocket topic: add a broadcastX function in websockets/helpers.ts so the frontend has a typed topic to subscribe to.
• Logging: log from monitoring/log. debug() from common/logger is fine for verbose dev logs but log carries structured context to Cloud Logging.
• Adding a domain helper: if a query is reused by more than one API endpoint, lift it into supabase/<domain>.ts here rather than duplicating it.

Build / test

yarn --cwd=backend/shared typecheck
yarn --cwd=backend/shared lint[-fix]
yarn --cwd=backend/shared test

Related docs

• ../../docs/database-connection-pooling.md
• ../../docs/performance-optimization.md
• ../../docs/LOGGING_logging-monitoringAND_MONITORING.md