Cursor rule

1---
2globs: apps/server/src/**/*
3---
4 
5## Backend Server (apps/server)
6 
7- **Role**: Thin WebSocket + HTTP edge that:
8  - Hosts a **`CoreContext` per WebSocket connection**.
9  - Exposes health/metrics endpoints.
10  - Delegates all business logic to `packages/core`.
11- Do **not** add business rules, Telegram API calls, or heavy data processing into `apps/server`; push those into `packages/core`.
12 
13### Bootstrap & Lifecycle
14 
15- Preserve the bootstrap sequence from `src/app.ts`:
16  1. Parse env flags (`parseEnvFlags`).
17  2. Initialize logging (`initLogger` + `useLogger().useGlobalConfig()`).
18  3. Build runtime config from environment (`parseEnvToConfig(process.env)`).
19  4. Initialize database via `initDrizzle` using that config.
20  5. Configure the HTTP/WebSocket server.
21  6. Start listening via `listhen` and register graceful shutdown handlers.
22- Any changes must keep this order clear and failure modes explicit.
23 
24### HTTP & WebSocket Design
25 
26- HTTP:
27  - Keep endpoints minimal: health checks, metrics, and potentially a small set of diagnostics.
28  - Reuse `h3` helpers (`createApp`, `createRouter`, `defineEventHandler`) and centralize error handling in `onError`.
29  - Never leak internal error details in HTTP responses; log full details, return generic messages.
30- WebSocket:
31  - Route all WS traffic through a dedicated module (e.g. `ws/routes`) that knows how to instantiate and manage `CoreContext`.
32  - Enforce **one `CoreContext` per connection**; no cross-connection sharing.
33  - When adding new events, ensure types are synchronized with `@tg-search/server/types` and `@tg-search/core`.
34 
35### Configuration & Environment
36 
37- Source configuration from `config.yaml` + environment variables only; avoid hard-coding URLs, ports, or credentials.
38- Keep the config schema compatible between server and browser modes where applicable (database, embedding, Telegram API).
39- When adding new configuration options:
40  - Document them in `.env.example`.
41  - Provide safe defaults that will not break existing deployments.
42 
43### Error Handling & Observability
44 
45- Use central error handlers:
46  - `setupErrorHandlers` for process-level errors (uncaughtException, unhandledRejection).
47  - `h3`'s `onError` hook for HTTP path errors.
48- Metrics:
49  - Use `prom-client` and expose metrics from `/metrics` using the shared registry.
50  - Only add new metrics when they support explicit SLOs (latency, error rate, throughput).
51 
52