umami/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Umami is a simple, fast, privacy-focused alternative to Google Analytics. It's built with Next.js 15 (App Router), TypeScript, and supports multiple database backends (PostgreSQL, ClickHouse, Kafka).

## Development Commands

### Package Manager
- Uses **pnpm** as the package manager (monorepo with `pnpm-workspace.yaml`)
- Install dependencies: `pnpm install`

### Development
- Start development server: `pnpm dev` (runs on port 3001 with Turbo)
- Build application: `pnpm build` (runs multiple build steps including database setup)
- Start production server: `pnpm start`
- Build for Docker: `pnpm build-docker`

### Database Operations
- Build Prisma client: `pnpm build-prisma-client`
- Update database schema: `pnpm update-db`
- Check database connection: `pnpm check-db`
- Seed test data: `pnpm seed-data`
- Change admin password: `pnpm change-password`

### Code Quality
- Lint: `pnpm lint` (uses Biome)
- Format: `pnpm format` (uses Biome)
- Check (lint + format): `pnpm check` (uses Biome)
- Test: `pnpm test` (uses Jest)
- Cypress E2E tests: `pnpm cypress-run` or `pnpm cypress-open`

### Tracker Script
- Build tracker script: `pnpm build-tracker` (rollup builds `/public/script.js`)
- Update tracker: `pnpm update-tracker`

### Internationalization
- Generate language files: `pnpm generate-lang`
- Format language files: `pnpm format-lang`
- Compile language files: `pnpm compile-lang`

## Architecture

### Tech Stack
- **Frontend**: Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS
- **Backend**: Next.js API routes, Prisma ORM, multiple database support
- **Database**: PostgreSQL (primary), ClickHouse (analytics), Kafka (event streaming)
- **State Management**: Zustand, React Query (TanStack)
- **Styling**: CSS Modules, Tailwind CSS, `@umami/react-zen` component library
- **Code Quality**: Biome (linting/formatting), TypeScript, Jest, Cypress

### Key Directories
- `src/app/` - Next.js App Router pages and API routes
  - `(collect)/` - Collection endpoints (pixels, links)
  - `(main)/` - Main application UI routes
  - `api/` - REST API endpoints
- `src/components/` - React components
  - `common/` - Shared UI components
  - `charts/` - Data visualization components
  - `hooks/` - Custom React hooks
- `src/lib/` - Utility libraries and shared logic
- `src/tracker/` - Analytics tracker JavaScript (built to `/public/script.js`)
- `src/styles/` - Global CSS and design tokens
- `prisma/` - Database schema and migrations
- `db/` - Database-specific schemas (PostgreSQL, ClickHouse)
- `scripts/` - Build and utility scripts

### Database Architecture
- **Primary Database**: PostgreSQL with Prisma ORM
- **Analytics Database**: ClickHouse for high-volume analytics data
- **Event Streaming**: Kafka for real-time event processing
- **Cache**: Redis for session and data caching
- Database type determined by `DATABASE_URL` environment variable
- Queries use `runQuery()` helper that routes to appropriate database

### API Structure
- RESTful API built with Next.js Route Handlers
- Authentication via JWT tokens
- Main collection endpoint: `/api/send` (handles analytics events)
- Admin endpoints under `/api/admin/`
- User/team management under `/api/me/`, `/api/users/`, `/api/teams/`
- Website analytics under `/api/websites/[websiteId]/`

### Tracker System
- JavaScript tracker at `/public/script.js` (built from `src/tracker/`)
- Configurable via data attributes on script tag
- Supports event tracking, page views, custom events
- Can be hosted externally via `TRACKER_SCRIPT_URL` env var
- Multiple script names supported via `TRACKER_SCRIPT_NAME` env var

### Environment Configuration
Required environment variables:
- `DATABASE_URL` - PostgreSQL connection string
- `APP_SECRET` - JWT secret key

Optional environment variables:
- `CLICKHOUSE_URL` - ClickHouse connection for analytics
- `KAFKA_URL` - Kafka connection for event streaming
- `REDIS_URL` - Redis connection for caching
- `CLOUD_MODE` - Enable cloud-specific features
- `COLLECT_API_ENDPOINT` - Custom endpoint for tracker
- `TRACKER_SCRIPT_NAME` - Alternative script names
- `DISABLE_UI` - Disable web interface (API-only mode)

## Development Notes

### Database Setup
1. Set `DATABASE_URL` in `.env` file
2. Run `pnpm build` to create database tables and admin user (admin/umami)
3. For ClickHouse analytics, also set `CLICKHOUSE_URL`

### Testing
- Unit tests: `pnpm test` (Jest with `src/lib/__tests__/`)
- E2E tests: `pnpm cypress-run` (requires running application)
- Test database: Uses separate test database configuration

### Code Style
- Uses Biome for formatting and linting (configured in `biome.json`)
- Line width: 100 characters
- Single quotes for strings
- Trailing commas in multiline objects/arrays
- TypeScript strict mode enabled

### Build Process
The `pnpm build` command runs multiple sequential steps:
1. `check-env` - Validate environment variables
2. `build-db` - Build Prisma client and database schema
3. `check-db` - Verify database connection
4. `build-tracker` - Build analytics tracker script
5. `build-geo` - Build GeoIP database
6. `build-app` - Build Next.js application

### Docker Deployment
- Docker image includes standalone Next.js output
- Uses multi-stage build for production optimization
- Includes all necessary dependencies
- Health check endpoint at `/api/heartbeat`

### Internationalization
- Uses `react-intl` for translations
- Messages extracted from `src/components/messages.ts`
- Compiled to `public/intl/messages/`
- Default locale: `en-US`, configurable via `DEFAULT_LOCALE` env var

## Common Tasks

### Adding a New API Endpoint
1. Create file in `src/app/api/[path]/route.ts`
2. Use `parseRequest()` helper for request validation
3. Use `runQuery()` for database operations
4. Return appropriate HTTP responses using helpers from `src/lib/response.ts`

### Adding a New Component
1. Create component in `src/components/` (organized by feature)
2. Use CSS Modules for styling (`*.module.css`)
3. Export TypeScript interfaces/types
4. Add to appropriate barrel file (`index.ts`) if needed

### Database Schema Changes
1. Update `prisma/schema.prisma`
2. Create migration: `prisma migrate dev --name description`
3. Update Prisma client: `pnpm build-prisma-client`
4. Update TypeScript types as needed

### Adding Tracker Features
1. Modify `src/tracker/index.js`
2. Rebuild tracker: `pnpm build-tracker`
3. Test with local development server

## Troubleshooting

### Database Connection Issues
- Verify `DATABASE_URL` format: `postgresql://user:pass@host:port/db`
- Check database is running and accessible
- Run `pnpm check-db` to test connection

### Build Failures
- Ensure all environment variables are set
- Check Node.js version (requires 18.18+)
- Clear `.next` cache if build issues persist

### Tracker Not Working
- Verify script is loaded: check browser console
- Check CORS headers if hosted on different domain
- Test with `/api/send` endpoint directly