mirror of
https://github.com/CompassConnections/Compass.git
synced 2026-07-31 18:28:47 -04:00
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# 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](../../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
|
|
|
|
```bash
|
|
yarn --cwd=backend/shared typecheck
|
|
yarn --cwd=backend/shared lint[-fix]
|
|
yarn --cwd=backend/shared test
|
|
```
|
|
|
|
## Related docs
|
|
|
|
- [`../../docs/database-connection-pooling.md`](../../docs/database-connection-pooling.md)
|
|
- [`../../docs/performance-optimization.md`](../../docs/performance-optimization.md)
|
|
- [`../../docs/LOGGING_logging-monitoringAND_MONITORING.md`](../../docs/logging-monitoring.md)
|