# CLAUDE.md

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

## Project Overview

**Harmonic SaaS** is a Nuxt Layer - a reusable foundation for building SaaS applications. It provides core SaaS functionality including authentication, database management, and internationalization that other Nuxt projects can extend.

## Technology Stack

- **Framework**: Nuxt 4 with Vue.js and TypeScript
- **Database**: PostgreSQL with Drizzle ORM
- **Authentication**: Better Auth with GitHub/Google OAuth + email/password
- **UI**: Nuxt UI with Tailwind CSS v4
- **Package Manager**: pnpm

## Essential Commands

```bash
# Development
pnpm dev                 # Start playground development server
pnpm dev:prepare         # Prepare playground environment

# Database Operations
pnpm db:generate         # Generate database migrations
pnpm db:migrate          # Run database migrations
pnpm db:push             # Push schema changes directly
pnpm db:studio           # Open Drizzle Studio

# Quality Assurance
pnpm lint                # ESLint with stylistic rules
pnpm test                # Run Vitest test suite
pnpm typecheck           # TypeScript type checking
pnpm coverage            # Generate test coverage

# Production
pnpm build               # Build for production
pnpm release             # Full release workflow (lint + coverage + release-it)
```

## Architecture

### Layer-Based Design
This is a **Nuxt Layer** designed for extension. Apps consume it via `extends: ['@vernaillen/harmonic-saas']` in nuxt.config.ts. The `.playground` directory serves as the development environment for testing the layer.

### Database Architecture
- **Location**: `/server/database/`
- **Schema**: Drizzle ORM with PostgreSQL in `/server/database/schema.ts`
- **Extensibility**: Apps can extend the schema using `registerTables()` function
- **Auth Tables**: `user`, `session`, `account`, `verification` tables included

### Authentication System
- **Better Auth** integration with multiple providers (email/password, GitHub, Google)
- **Global middleware** for route protection (guest/user redirects)
- **Protected routes** in `/app/pages/dashboard/` by default
- **Session management** with reactive state using `useState`

### Directory Structure
- **`/app`** - Frontend code (pages, components, composables, middleware)
- **`/server`** - Backend API routes, database schema, utilities
- **`/.playground`** - Development environment for testing the layer
- **`/examples`** - Example implementations
- **`/test`** - Test suite with multiple environments (unit, e2e, nuxt)
- **`/i18n`** - Internationalization (Dutch/English support)

### Environment Requirements
Required environment variables (all prefixed with `NUXT_`):
- `NUXT_DATABASE_URL` - PostgreSQL connection string
- `NUXT_BETTER_AUTH_SECRET` - Secret key for Better Auth
- `NUXT_BETTER_AUTH_URL` - Base URL for Better Auth (e.g., http://localhost:3000)
- `NUXT_GITHUB_CLIENT_ID` / `NUXT_GITHUB_CLIENT_SECRET` - GitHub OAuth (optional)
- `NUXT_GOOGLE_CLIENT_ID` / `NUXT_GOOGLE_CLIENT_SECRET` - Google OAuth (optional)
- `NUXT_RESEND_API_KEY` / `NUXT_FROM_EMAIL` - Email service (optional, falls back to mock mode)

## Testing Strategy

Multi-environment testing with Vitest:
- **Unit tests**: Node environment
- **E2E tests**: Browser environment
- **Nuxt tests**: Nuxt-specific environment
- **Coverage**: Integrated coverage reporting

## Internationalization

- **Locales**: Dutch (default) and English
- **File location**: `/i18n/locales/`
- **Strategy**: Prefix except default (e.g., `/en/...` for English routes)
- **Auto-detection**: Browser language detection with cookie persistence

## Key Development Patterns

### Schema Extension
Apps extending this layer can add custom database tables:

```typescript
// In extending app's server/database/registerTables.ts
import { registerTables } from '@vernaillen/harmonic-saas/server/database'

registerTables({
  customTable: myCustomTableSchema
})
```

### Authentication Middleware
Routes in `/app/pages/dashboard/` are automatically protected. Use `definePageMeta({ auth: false })` to make pages public.

### Database Connection
Use the singleton `db` instance from `/server/database/connection.ts`. Connection pooling is handled automatically.

## Development Workflow

1. **Start development**: `pnpm dev` boots the `.playground` environment
2. **Database changes**: Use `pnpm db:generate` then `pnpm db:migrate`
3. **Testing**: Always run `pnpm test` and `pnpm typecheck` before committing
4. **Release**: Use `pnpm release` for version bumps and publishing

## Layer Distribution

This project is published as `@vernaillen/harmonic-saas` on NPM. Apps consume it by adding it to the `extends` array in their Nuxt configuration.
