# CLAUDE.md

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

## Commands

```bash
# Development
npm run dev                   # Start dev server on :3000
npm run build                 # Production build
npm run start                 # Start production server

# Code quality
npm run lint                  # ESLint check
npm run lint:fix              # Auto-fix ESLint issues
npm run format                # Prettier check
npm run format:fix            # Auto-format with Prettier

# Testing
npm test                      # Run all Jest tests
npm test -- --testPathPattern=user.service  # Run a single test file

# Database migrations (TypeORM)
npm run typeorm:migration                              # Run pending migrations
npm run typeorm:migration:down                         # Revert last migration
npm run typeorm:create --name=<migration-name>        # Create a new migration file

# Local infrastructure (PostgreSQL + S3-compatible storage)
docker compose -f docker/docker-compose.yml up -d
```

## Architecture

This is a **Next.js 16 App Router** full-stack blog with TypeScript. The structure separates concerns into three main layers:

### Frontend (`src/app/` + `src/ui/`)

- **Pages** live in `src/app/(pages)/` using route groups
- **API routes** live in `src/app/api/` (Next.js Route Handlers)
- **Components** in `src/ui/components/internal/` (custom) and `src/ui/components/shadcn/` (shadcn/ui generated)
- **Providers** in `src/ui/providers/` wrap the app with React Query, Jotai, and Clerk
- Root layout at `src/app/layout.tsx` mounts all providers; `/` redirects to `/home` via `next.config.ts`

### Backend (`src/lib/`)

Domain-driven feature modules — each feature lives in `src/lib/feature/<feature>/` with:

- `*.entity.ts` — TypeORM entity definition
- `*.model.ts` — DTOs and interfaces (Zod schemas live here too)
- `*.service.ts` — Business logic (CRUD, validation, no HTTP concerns)
- `*.external.ts` — External integrations (Clerk, etc.)

Current features: `user/`, `article/`

### Key Integrations

- **Auth:** Clerk (`@clerk/nextjs`) handles auth. On sign-in, `/api/user/sync` syncs the Clerk user into PostgreSQL via `user.service.ts`. Sessions are stored server-side via `iron-session` (`src/lib/session/`).
- **Database:** PostgreSQL 16 via TypeORM. `src/lib/db/data-source.ts` is used at runtime; `src/lib/db/data-source.cli.ts` is used by the TypeORM CLI. Entities are exported from `src/lib/db/entities.ts`.
- **Storage:** `src/lib/storage/` provides a `StorageProvider` interface with an `S3StorageAdapter` implementation (AWS SDK v3). The factory in `storage.factory.ts` selects the provider; `storage.ts` exports the singleton. `put()` returns a presigned URL.
- **Migrations:** SQL migrations in `migrations/` directory. Run via TypeORM CLI, not auto-run.

### State management

- **Server state:** React Query (`@tanstack/react-query`) for async data fetching
- **Client state:** Jotai atoms for local UI state
- **Forms:** React Hook Form + Zod validation

### Testing

- Jest with `ts-jest`; tests in `tests/` mirroring `src/lib/` structure
- PostgreSQL integration tests use `@testcontainers/postgresql` (requires Docker)
- S3 tests use `aws-sdk-client-mock`

### Local environment

Docker Compose starts PostgreSQL on port **5332** and Rustfs (S3-compatible) on ports **9000/9001**. Environment variables are in `.env`; key ones: `DATABASE_URL`, `SESSION_SECRET`, `CLERK_*`, `S3_*`.