development.md

Development

Use rtk before shell commands in this repository.

Checks

Run focused checks after narrow edits, then broader checks before finishing:

rtk bun run typecheck
rtk bun run lint
rtk bun test
rtk uv run ruff check .
rtk uv run pytest services/analytics-worker

Use targeted test paths while iterating. Run integration checks only when the change touches the database, NATS JetStream, object storage, or local stack behavior being verified.

Module Boundaries

• Inspect the existing module and nearest ownership docs before adding code.
• Keep API handlers, CLI scripts, and message consumers thin.
• Put business rules in domain/application modules and I/O in infrastructure or entrypoints.
• Keep TypeScript strict and Python public functions typed.
• Do not add cross-service imports; use shared packages for shared behavior.
• Do not introduce circular dependencies or global mutable state.
• Do not create large catch-all files named utils, helpers, common, or misc.
• Preserve public contracts and behavior unless the active task explicitly changes them.

Python analytics runs on Python 3.13 via uv. TypeScript services run on Bun with Biome and strict TypeScript.