77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# 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_*`.
|