|
| 1 | +# WARP.md |
| 2 | + |
| 3 | +This file provides guidance to WARP (warp.dev) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Databuddy is a comprehensive analytics and data management platform built as a monorepo using Turborepo, Bun, and modern web technologies. The platform provides real-time analytics, user tracking, and data visualization capabilities. |
| 8 | + |
| 9 | +## Core Architecture |
| 10 | + |
| 11 | +### Monorepo Structure |
| 12 | + |
| 13 | +This is a Turborepo monorepo with the following key applications and packages: |
| 14 | + |
| 15 | +**Applications (`apps/`):** |
| 16 | +- `dashboard/` - Next.js 15 frontend application (main analytics dashboard) |
| 17 | +- `api/` - Elysia.js backend API server with tRPC |
| 18 | +- `database/` - Database management UI (Next.js) |
| 19 | +- `basket/` - Data collection service |
| 20 | +- `docs/` - Documentation site |
| 21 | + |
| 22 | +**Packages (`packages/`):** |
| 23 | +- `sdk/` - Analytics SDK for React/Vue (published package) |
| 24 | +- `db/` - Database layer with Drizzle ORM (PostgreSQL + ClickHouse) |
| 25 | +- `rpc/` - tRPC API definitions and procedures |
| 26 | +- `auth/` - Authentication system |
| 27 | +- `redis/` - Redis client and utilities |
| 28 | +- `validation/` - Zod schemas and validation |
| 29 | +- `email/` - Email templates and sending |
| 30 | +- `shared/` - Shared types and utilities |
| 31 | +- `env/` - Environment variable validation |
| 32 | + |
| 33 | +### Technology Stack |
| 34 | + |
| 35 | +- **Runtime**: Bun (required for all operations) |
| 36 | +- **Frontend**: Next.js 15 with React 19, TypeScript 5.8+ |
| 37 | +- **Backend**: Elysia.js with tRPC |
| 38 | +- **Database**: PostgreSQL (via Drizzle ORM) + ClickHouse (analytics) |
| 39 | +- **Cache**: Redis |
| 40 | +- **Styling**: Tailwind CSS 4.x |
| 41 | +- **Icons**: Phosphor Icons (only, never Lucide) |
| 42 | +- **State**: Jotai + TanStack Query |
| 43 | +- **Forms**: React Hook Form + Zod v4 |
| 44 | +- **Dates**: Dayjs (never date-fns) |
| 45 | +- **Linting**: Ultracite (Biome-based) |
| 46 | + |
| 47 | +## Development Commands |
| 48 | + |
| 49 | +### Essential Commands (Always use `bun`) |
| 50 | + |
| 51 | +```bash |
| 52 | +# Install dependencies |
| 53 | +bun install |
| 54 | + |
| 55 | +# Development (starts all apps) |
| 56 | +bun run dev |
| 57 | + |
| 58 | +# Build all packages/apps |
| 59 | +bun run build |
| 60 | + |
| 61 | +# Database operations |
| 62 | +bun run db:push # Push schema changes |
| 63 | +bun run db:studio # Open Drizzle Studio |
| 64 | +bun run db:migrate # Run migrations |
| 65 | +bun run db:seed <WEBSITE_ID> [DOMAIN] [EVENT_COUNT] # Seed test data |
| 66 | + |
| 67 | +# SDK build (required before dev) |
| 68 | +bun run sdk:build |
| 69 | + |
| 70 | +# Individual app development |
| 71 | +bun run dashboard:dev # Dashboard only |
| 72 | + |
| 73 | +# Linting and formatting |
| 74 | +bun run lint # Lint with Ultracite |
| 75 | +bun run format # Format with Ultracite |
| 76 | +bun run check-types # TypeScript check |
| 77 | + |
| 78 | +# Testing |
| 79 | +bun run test # Run tests with Vitest |
| 80 | + |
| 81 | +# Email development |
| 82 | +bun run email:dev # Email templates server |
| 83 | +``` |
| 84 | + |
| 85 | +### Testing Commands |
| 86 | + |
| 87 | +```bash |
| 88 | +# Run all tests |
| 89 | +bun run test |
| 90 | + |
| 91 | +# Run specific test file |
| 92 | +bun test path/to/test.ts |
| 93 | + |
| 94 | +# Watch mode |
| 95 | +bun test --watch |
| 96 | +``` |
| 97 | + |
| 98 | +## Critical Development Rules |
| 99 | + |
| 100 | +### Package Manager |
| 101 | +- **ALWAYS use `bun`** - Never use npm, pnpm, or Node.js commands |
| 102 | +- Package manager is enforced via `.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc` |
| 103 | + |
| 104 | +### Code Quality Standards |
| 105 | +- **Ultracite**: Strict linting/formatting (subsecond performance, AI-friendly) |
| 106 | +- **Type Safety**: No `any`, `unknown`, `never` types - use explicit types from `@shared/types` |
| 107 | +- **Zod v4**: Required everywhere (from `zod/v4`, not v3) |
| 108 | +- **Error Handling**: Never throw in server actions - use try/catch and return errors |
| 109 | +- **React**: Almost never use `useEffect` unless critical |
| 110 | + |
| 111 | +### UI/UX Standards |
| 112 | +- **Icons**: Only Phosphor Icons (`@phosphor-icons/react`) - use `Icon` suffix |
| 113 | +- **Border Radius**: Always use `rounded` (never `rounded-xl`, `rounded-md`) |
| 114 | +- **Dates**: Dayjs only (never date-fns) |
| 115 | +- **State Management**: TanStack Query for data fetching (never SWR) |
| 116 | +- **Naming**: lower-case-kebab-case for files/components |
| 117 | +- **No Mock Data**: Never add placeholders or mock data |
| 118 | + |
| 119 | +### Architecture Patterns |
| 120 | +- **Modularity**: Split components/utils for reusability and performance |
| 121 | +- **Complexity**: Favor less complex, fewer-line solutions |
| 122 | +- **Mobile First**: Always consider mobile responsiveness |
| 123 | +- **Error Boundaries**: Always implement properly |
| 124 | +- **Console Usage**: Use appropriate methods (`console.error`, `console.time`, `console.json`) |
| 125 | + |
| 126 | +## Database Architecture |
| 127 | + |
| 128 | +### Primary Database (PostgreSQL) |
| 129 | +- **ORM**: Drizzle ORM |
| 130 | +- **Migrations**: Located in `packages/db/` |
| 131 | +- **Studio**: Access via `bun run db:studio` |
| 132 | + |
| 133 | +### Analytics Database (ClickHouse) |
| 134 | +- **Purpose**: High-performance analytics and event storage |
| 135 | +- **Setup**: `bun run clickhouse:init` |
| 136 | +- **Access**: Via `packages/db/clickhouse/` |
| 137 | + |
| 138 | +### Redis Cache |
| 139 | +- **Package**: `@databuddy/redis` |
| 140 | +- **Usage**: Session storage, caching, rate limiting |
| 141 | + |
| 142 | +## API Architecture |
| 143 | + |
| 144 | +### tRPC Setup |
| 145 | +- **Definitions**: `packages/rpc/src/` |
| 146 | +- **Client**: Auto-generated TypeScript client |
| 147 | +- **Server**: Elysia.js integration in `apps/api/` |
| 148 | + |
| 149 | +### Authentication |
| 150 | +- **Package**: `@databuddy/auth` |
| 151 | +- **Method**: Better Auth integration |
| 152 | +- **Providers**: Google, GitHub |
| 153 | + |
| 154 | +## SDK Architecture |
| 155 | + |
| 156 | +The `@databuddy/sdk` package provides analytics tracking for external applications: |
| 157 | + |
| 158 | +- **Core**: Framework-agnostic analytics client |
| 159 | +- **React**: React-specific hooks and components |
| 160 | +- **Vue**: Vue 3 composables and components |
| 161 | +- **Build**: Uses Unbuild for multi-format output |
| 162 | + |
| 163 | +## Environment Setup |
| 164 | + |
| 165 | +### Required Services |
| 166 | +- PostgreSQL database |
| 167 | +- Redis server |
| 168 | +- ClickHouse (for analytics) |
| 169 | +- Cloudflare account (deployment) |
| 170 | +- Vercel account (deployment) |
| 171 | + |
| 172 | +### Environment Files |
| 173 | +- Copy `.env.example` to `.env` |
| 174 | +- Configure database URLs, API keys, and service credentials |
| 175 | + |
| 176 | +## Important Workspace Features |
| 177 | + |
| 178 | +### Turborepo Configuration |
| 179 | +- **Caching**: Build artifacts cached for performance |
| 180 | +- **Dependencies**: Managed via workspace protocol |
| 181 | +- **Pipelines**: Defined in `turbo.json` |
| 182 | + |
| 183 | +### Shared Dependencies (Catalog) |
| 184 | +Key shared versions defined in root `package.json`: |
| 185 | +- React 19.0.0 |
| 186 | +- Next.js 15.3.4+ |
| 187 | +- TypeScript 5.8.3+ |
| 188 | +- Zod 3.25.76 (workspace packages use v4) |
| 189 | +- Tailwind CSS 4.1.4+ |
| 190 | + |
| 191 | +## Testing Strategy |
| 192 | + |
| 193 | +- **Framework**: Vitest 3.x |
| 194 | +- **Location**: Tests alongside source files (`.test.ts` suffix) |
| 195 | +- **Coverage**: Available via `@vitest/coverage-v8` |
| 196 | +- **Example**: See `apps/basket/src/hooks/auth.test.ts` |
| 197 | + |
| 198 | +## Deployment Architecture |
| 199 | + |
| 200 | +- **Dashboard**: Vercel (Next.js app) |
| 201 | +- **API**: Deployed separately (Elysia.js) |
| 202 | +- **Database**: PostgreSQL + ClickHouse cluster |
| 203 | +- **CDN**: Cloudflare for static assets and edge functions |
| 204 | + |
| 205 | +## Development Workflow |
| 206 | + |
| 207 | +1. **Setup**: `bun install` → `bun run db:push` → `bun run sdk:build` |
| 208 | +2. **Development**: `bun run dev` (starts all services) |
| 209 | +3. **Database**: Use `bun run db:studio` for visual management |
| 210 | +4. **Testing**: `bun run test` for validation |
| 211 | +5. **Linting**: Automatic via Ultracite on save |
| 212 | + |
| 213 | +## Key Files to Understand |
| 214 | + |
| 215 | +- `turbo.json` - Monorepo build pipeline configuration |
| 216 | +- `packages/db/src/schema/` - Database schema definitions |
| 217 | +- `packages/rpc/src/` - API route definitions and types |
| 218 | +- `apps/dashboard/` - Main user interface |
| 219 | +- `.cursor/rules/` - Development standards and constraints |
| 220 | + |
| 221 | +## Performance Considerations |
| 222 | + |
| 223 | +- **Build Performance**: Turborepo caching + Bun's speed |
| 224 | +- **Runtime Performance**: React 19 + Next.js 15 optimizations |
| 225 | +- **Database Performance**: ClickHouse for analytics, PostgreSQL for transactional |
| 226 | +- **SDK Performance**: Minimal bundle size, tree-shakeable |
| 227 | + |
| 228 | +## Security & Compliance |
| 229 | + |
| 230 | +- **Authentication**: Better Auth with OAuth providers |
| 231 | +- **Data Protection**: GDPR compliant data handling |
| 232 | +- **API Security**: Rate limiting via Upstash Redis |
| 233 | +- **Environment**: Secure environment variable handling via `@databuddy/env` |
0 commit comments