Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
docs: add AGENTS.md contributor guidance
Mike Cao57c4a6ed5135
diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..764b35112--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,97 @@+# AGENTS.md++This file provides guidance for AI coding agents working in this repository.++## Project overview++Umami is a privacy-focused web analytics platform built with Next.js 15, React 19, and TypeScript.++- Primary database: PostgreSQL+- Optional analytics backend: ClickHouse+- Optional cache/session backend: Redis++## Development rules++- Assume a dev server is already running on port `3001`.+- Do **not** start another dev server.+- Use `pnpm` (not `npm` or `yarn`).+- Avoid destructive shell commands unless explicitly requested.+- Ask before running `git commit` or `git push`.++## Common commands++```bash+# Development+pnpm dev+pnpm build+pnpm start++# Database+pnpm build-db+pnpm update-db+pnpm check-db+pnpm seed-data++# Code quality+pnpm lint+pnpm format+pnpm check+pnpm test++# Build specific parts+pnpm build-tracker+pnpm build-geo+```++## Architecture++- `src/app/`: Next.js App Router routes and API endpoints+- `src/components/`: UI components and hooks+- `src/lib/`: shared utilities and infrastructure helpers+- `src/queries/`: data access layer (Prisma + raw SQL)+- `src/store/`: Zustand stores+- `src/tracker/`: standalone client tracking script+- `prisma/`: schema and migrations++## Key implementation patterns++### API request validation++Use Zod + `parseRequest` in API handlers:++```ts+const schema = z.object({ /* fields */ });+const { body, error } = await parseRequest(request, schema);+if (error) return error();+```++### Authentication++- JWT via `Authorization: Bearer <token>`+- Share token via `x-umami-share-token`+- Role model: `admin`, `manager`, `user`++### Client data fetching++- React Query defaults: `staleTime` 60s, no retry, no refetch on window focus++### Styling++- CSS Modules with CSS variables and theme support++## Environment variables++Common env vars:++- `DATABASE_URL`+- `APP_SECRET`+- `CLICKHOUSE_URL`+- `REDIS_URL`+- `BASE_PATH`+- `DEBUG`++## Runtime requirements++- Node.js 18.18++- PostgreSQL 12.14++- `pnpm`