Copilot instructions

1# Copilot Instructions for telegram-search
2 
3This repo is a pnpm-powered monorepo for a Telegram search/export app. It uses an event-driven core with WebSocket bridging, Vue 3 frontend, and Drizzle ORM for storage (PostgreSQL + pgvector or in-browser PGlite).
4 
5## Architecture essentials
6- Monorepo layout:
7  - `apps/web`: Vue 3 app (Pinia, TanStack Query). Can run standalone with `VITE_WITH_CORE=true` (browser-only mode with PGlite).
8  - `apps/server`: WebSocket server (h3) that hosts the Core for server mode.
9  - `packages/core`: Event-driven Core (EventEmitter3), services, DB models and resolvers.
10  - `packages/client`: Browser-side bridge + client event handlers and stores.
11  - `packages/common`: Shared config, logger wrapper, utils.
12- Core event bus: `packages/core/src/context.ts` creates `CoreContext` around EventEmitter3. All cross-layer comms use events:
13  - To Core (requests): `auth:*`, `message:*`, `dialog:*`, `entity:*`, `storage:*`, `takeout:*`, etc.
14  - From Core (results): e.g. `auth:connected`, `message:data`, `dialog:data`, `storage:search:messages:data`.
15  - Event types and contracts live in `packages/core/src/types/events.ts`. Follow `<domain>:<action>` naming.
16- Event handlers and services:
17  - Handlers: `packages/core/src/event-handlers/*.ts` map bus events to services.
18  - Services: `packages/core/src/services/*.ts` implement business logic and emit results.
19  - Message pipeline resolvers in `packages/core/src/message-resolvers/*` (embedding, jieba, link, media, user) operate independently and stream results.
20- Client bridge:
21  - `packages/client/src/adapters/core-bridge.ts` initializes config/logger, creates Core in browser mode, registers handlers, and forwards events between UI and Core (or WebSocket server).
22  - For server mode, the browser uses a WebSocket adapter; the server routes events to a per-connection Core instance.
23- Database:
24  - Drizzle ORM schemas/models under `packages/core/src/{schemas,models}`; migrations in `drizzle/`.
25  - Two modes: PostgreSQL+pgvector (server) and PGlite (browser). Code paths must support both.
26 
27## Dev workflows
28- Node 24+ and pnpm required. Root scripts:
29  - Browser-only: `pnpm dev` (equivalent to `VITE_WITH_CORE=true pnpm -F @tg-search/web dev`).
30  - Server mode: `pnpm server:dev` and `pnpm web:dev` (two terminals). DB via `docker compose up -d pgvector`.
31  - Builds: `pnpm build`, `pnpm web:build`, `pnpm server:build`, `pnpm packages:build`.
32  - Types/tests/lint: `pnpm typecheck` (builds packages first), `pnpm test` (Vitest), `pnpm lint` / `pnpm lint:fix`.
33  - DB tools: `pnpm db:generate` (drizzle-kit).
34- Config:
35  - Browser mode uses `.env` (`VITE_TELEGRAM_API_ID`, `VITE_TELEGRAM_API_HASH`).
36  - Server mode uses environment variables (database, Telegram API, optional proxy) loaded via `.env` / `.env.local` and dotenvx. See `docs/ENVIRONMENT.md`.
37 
38## Conventions and patterns
39- Events are the API. Don’t call services directly across layers; emit on `ctx.emitter` and listen for results. Use types from `packages/core/src/types/events.ts`.
40- Naming:
41  - Event names: `<domain>:<action>` (e.g. `message:fetch`, `storage:search:messages`). Avoid timestamps for ordering—prefer Telegram message IDs.
42  - Files: kebab-case; components: PascalCase; constants: UPPER_SNAKE_CASE.
43- Logging & errors:
44  - Use `@guiiai/logg` (`useLogger()`). Include `withFields` context and `withError` on failures.
45  - Use `ctx.withError(err, description)` to emit `core:error` and log uniformly. In dev, `CoreContext` tracks listener counts and warns on potential leaks; emit `core:cleanup` when tearing down a context.
46- Session isolation:
47  - Each browser tab/WS connection has its own `CoreContext` and event subscriptions. Avoid global singletons in core logic.
48- Storage/search specifics:
49  - Vector search via embeddings (OpenAI/Ollama). Resolvers live under `packages/core/src/message-resolvers/embedding-resolver.ts` etc.
50  - Storage/search events: `storage:search:messages` -> emits `storage:search:messages:data` with ranked results.
51 
52## Where to look for examples
53- Event contracts: `packages/core/src/types/events.ts` (e.g., `MessageEventToCore`, `StorageEventFromCore`).
54- Handler -> service pattern: `packages/core/src/event-handlers/message.ts` and `packages/core/src/services/message.ts`.
55- Client event bridging: `packages/client/src/adapters/core-bridge.ts`.
56- DB schema and migrations: `packages/core/src/schemas/*`, `drizzle/*`.
57 
58## Gotchas and edge cases
59- Message ordering: always use Telegram Message ID over timestamps.
60- Dual DB mode: ensure code paths work for both Postgres and PGlite; avoid vendor-specific SQL in core logic.
61- Avoid memory leaks: unsubscribe listeners on cleanup and prefer one-time listeners when appropriate.
62