hideyoshi-blog/CLAUDE.md

CLAUDE.md

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

Commands

# 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_*.