Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (49 loc) · 3.8 KB

AGENTS.md

File metadata and controls

66 lines (49 loc) · 3.8 KB
Raw

Umami

Privacy first web analytics: one Next.js app that both collects events (the tracker and the collect routes) and reports on them (the dashboard).

Stack

  • Language / Runtime: TypeScript 6, Node 22 (CI pins 22, README floor is 18.18)
  • Framework: Next.js 16 App Router, React 19 (React Compiler enabled), ESM only
  • Key dependencies: Prisma 7 (@prisma/adapter-pg), @clickhouse/client, TanStack Query, Zustand, @umami/react-zen (the UI kit), next-intl, Zod
  • Data: PostgreSQL always, plus ClickHouse and optional Kafka and Redis once scaled
  • Package manager: pnpm 10.15.1

Build approach

<TBD, set by /scope>

Commands

pnpm install            # install
pnpm dev                # dev server (Turbopack, loads .env)
pnpm build              # full build: env check, prisma client, tracker, recorder, geo, app
pnpm test               # Vitest unit and component tests
pnpm test:e2e           # Playwright end to end tests
pnpm check              # Biome lint and format, writes fixes

Specs

Stored in docs/specs/. Format: docs/specs/NNNN-title.md.

Rules

  • Import through the @/ alias, which maps to src/. No deep relative climbs.
  • Biome is the only linter and formatter: single quotes, trailing commas, 2 space indent, 100 column width. Run pnpm check before you commit.
  • Pull requests target the dev branch, never master. See CONTRIBUTING.md.
  • Never touch a database client from a route or component. Reads and writes go through src/queries.
  • Every API route validates with Zod, authenticates through parseRequest, checks a @/permissions function, and replies through the helpers in src/lib/response.ts.
  • No user facing string is hardcoded. Add a key to src/components/messages.ts and read it with useMessages().
  • Build UI from @umami/react-zen primitives first. Reach for a CSS module only when a primitive cannot do it.
  • Tests sit beside the code they cover as *.test.ts or *.test.tsx. Details in src/test/README.md.
  • src/generated/ and public/script.js are build output. Never edit them by hand.

Agent skills

  • clickhouse-best-practices: clickhouse/agent-skills, ClickHouse schema and query conventions, which govern the analytics half of src/queries/sql
  • architect: jsmastery-pro/skills, design decisions, owns docs/specs/
  • audit: jsmastery-pro/skills, bootstraps these context files
  • check: jsmastery-pro/skills, verification and code review before merge
  • debug: jsmastery-pro/skills, root cause loop for a failing behavior
  • develop: jsmastery-pro/skills, builds a feature from an approved spec
  • document: jsmastery-pro/skills, PR text, changelogs, release notes
  • scope: jsmastery-pro/skills, keeps docs/scope/ current
  • sync: jsmastery-pro/skills, refreshes these files after a change
  • test: jsmastery-pro/skills, writes the suite for new code

MCP servers: prisma (recommended, needs authorizing)

Context files

Drafted by /audit from the repo, worth a quick human pass. Edit freely: once a line stops matching this draft, later runs treat it as curated and will flag rather than overwrite it.