This commit is contained in:
apple
187
CLAUDE.md
Normal file
187
CLAUDE.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user