🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
AGENTS.md - Rybbit Server
Guidance for agents working in the server package. Keep changes scoped to this package unless the task explicitly requires changes in client or shared.
Commands
Run package commands from server/. Install dependencies at the repository
root with pnpm install. The root pnpm dev:server and pnpm build:server
commands build shared first; use them on a fresh checkout. Docs is separate.
pnpm run dev- compile TypeScript and startdist/index.js.pnpm run dev:cluster- compile TypeScript and start the cluster entrypoint.pnpm run build- compile TypeScript and rebuild the analytics script.pnpm run start- run the compiled single-process server.pnpm run start:cluster- run the compiled cluster server.pnpm run test:run- run Vitest once.pnpm run test:watch- run Vitest in watch mode.pnpm run test- run Vitest.pnpm run db:check- check Drizzle migrations.pnpm run format- run Prettier over server source files.pnpm run format:check- check formatting.
Do not run database migration, push, pull, or drop commands unless the user explicitly asks for them. Avoid editing dist/; make source changes in src/ and rebuild when needed.
Stack
- Fastify 5 for HTTP routing.
- TypeScript ESM; source imports use
.jsspecifiers for compiled output. - Better Auth for authentication.
- Drizzle ORM with Postgres for relational data.
- ClickHouse for analytics event storage and querying.
- Zod for request validation.
- Cron jobs and service classes for background work.
- Vitest for tests.
- Pino via Fastify logger for logging.
Project Layout
src/index.ts- Fastify server setup, middleware, static files, and route registration.src/cluster.ts- cluster entrypoint.src/api/- route handlers grouped by domain.src/api/analytics/- analytics query endpoints.src/api/sites/- site management, imports, tracking config, and script verification.src/api/user/,src/api/teams/,src/api/memberAccess/- account, organization, team, and access APIs.src/api/stripe/- billing and Stripe webhook handlers.src/db/postgres/- Drizzle schema, client setup, and Postgres helpers.src/db/clickhouse/- ClickHouse client, migrations, and analytics storage helpers.src/lib/- auth middleware, auth utilities, constants, logger helpers, and shared server utilities.src/services/- domain services for tracking, sessions, replay, imports, reporting, storage, and email.src/analytics-script/- browser analytics script source and build tooling.drizzle/- generated SQL migration files.public/- served browser assets such as tracking and replay scripts.
Routing And Handlers
- Register routes in
src/index.tswith the existing Fastify plugin/grouping style. - Put domain handler implementations in
src/api/[domain]/. - Export handlers through that domain's
index.tsbarrel when one exists. - Use the existing auth pre-handler chains in
src/index.tswhere possible:publicSite,authSite,adminSite,authOnly,adminOnly,orgMember, andorgAdminParams. - Type Fastify requests with explicit
Params,Querystring, andBodyshapes. - Validate untrusted request bodies and query params with Zod before using them.
Data Access
- Use Drizzle helpers and schema objects from
src/db/postgres/for Postgres access. - Keep Postgres schema changes in
src/db/postgres/schema.ts; generate migrations only when the user asks for migration files. - Use ClickHouse helpers for analytics event queries instead of hand-building duplicate client code.
- Be careful with analytics query filters and timezones; reuse existing utilities in
src/api/analytics/utils/and related modules. - Never interpolate untrusted input directly into SQL. Use query builders, parameterization, or existing escaping helpers.
Services
- Keep business logic that is reused or long-running in
src/services/. - Keep route handlers thin when a service already exists for the domain.
- For tracking endpoints, preserve performance-sensitive behavior and avoid adding synchronous work to hot paths.
- For background services, ensure startup side effects remain intentional and compatible with both single-process and cluster modes.
Conventions
- TypeScript strict mode is expected.
- Use
camelCasefor variables and functions,PascalCasefor types and classes, andUPPER_SNAKE_CASEfor constants. - Group imports by external dependencies first, then internal modules; keep each group alphabetized where practical.
- Preserve ESM import style with
.jsextensions for local TypeScript modules. - Prefer specific error responses with appropriate status codes over generic throws in request handlers.
- Avoid broad abstractions, unrelated refactors, or comments that merely repeat the code.
Verification
For most server changes, run:
pnpm run buildpnpm run test:run
Run targeted Vitest files while iterating, for example pnpm exec vitest run src/utils.test.ts.