claude-code-hub/CLAUDE.md

CLAUDE.md

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

Repository Info

• Source: https://github.com/ding113/claude-code-hub
• PR Target Branch: dev (all pull requests must target the dev branch)

Critical Rules

1. No Emoji in Code - Never use emoji characters in any code, comments, or string literals
2. Test Coverage - All new features must have unit test coverage of at least 80%
3. i18n Required - All user-facing strings must use i18n (5 languages supported). Never hardcode display text

4. Pre-commit Checklist - Before committing, always run:

   bun run build      # Production build
   bun run lint       # Biome check
   bun run lint:fix   # Biome auto-fix
   bun run typecheck  # TypeScript check (uses tsgo)
   bun run test       # Run Vitest tests
   

Build & Development Commands

# Development
bun install               # Install dependencies
bun run dev               # Start dev server (port 13500)

# Build & Production
bun run build             # Build for production (copies VERSION to standalone)
bun run start             # Start production server

# Quality Checks
bun run typecheck         # Type check with tsgo (faster)
bun run typecheck:tsc     # Type check with tsc
bun run lint              # Lint with Biome
bun run lint:fix          # Auto-fix lint issues
bun run format            # Format code

# Testing
bun run test              # Run unit tests (vitest)
bun run test:ui           # Interactive test UI
bun run test:coverage     # Coverage report
bunx vitest run <file>    # Run single test file
bunx vitest run -t "test name"  # Run specific test

# Dev environment (via dev/Makefile)
cd dev && make dev        # Start all services (PG + Redis + app)
cd dev && make db         # Start only database services

Database Migration Workflow

IMPORTANT: Never create SQL migration files manually. Always follow this workflow:

1. Modify schema - Edit src/drizzle/schema.ts
2. Generate migration - Run bun run db:generate
3. Review generated SQL - Check the generated file in drizzle/ directory
4. Edit if necessary - Make any required adjustments to the generated SQL

5. Apply migration - Run bun run db:migrate or let AUTO_MIGRATE=true handle it on startup

   bun run db:generate       # Generate Drizzle migrations from schema changes
   bun run db:migrate        # Apply migrations
   bun run db:push           # Push schema changes (dev only)
   bun run db:studio         # Open Drizzle Studio
   

Architecture Overview

Tech Stack

• Framework: Next.js 16 (App Router) + Hono for API routes
• Database: PostgreSQL (Drizzle ORM) + Redis (ioredis)
• UI: React 19 + shadcn/ui + Tailwind CSS + Recharts
• Package Manager: Bun (1.3+)
• Testing: Vitest + happy-dom

Directory Structure

src/
├── app/
│   ├── [locale]/dashboard/    # Dashboard UI pages
│   ├── api/                   # Internal API routes
│   └── v1/                    # Proxy API (Claude/OpenAI compatible)
│       └── _lib/
│           ├── proxy/         # Core proxy pipeline
│           ├── converters/    # Format converters (claude/openai/codex/gemini)
│           └── codex/         # Codex CLI adapter
├── actions/                   # Server Actions (exposed via /api/actions)
├── lib/                       # Core business logic
│   ├── session-manager.ts     # Session & context caching
│   ├── circuit-breaker.ts     # Provider health management
│   ├── rate-limit/            # Multi-dimensional rate limiting
│   └── redis/                 # Redis utilities
├── repository/                # Drizzle ORM data access layer
└── drizzle/
    └── schema.ts              # Database schema definition

Core Proxy Flow

The proxy pipeline (src/app/v1/_lib/proxy-handler.ts) processes requests through a guard chain:

Request -> GuardPipeline -> [auth -> sensitive -> client -> model -> version -> probe ->
                            session -> warmup -> requestFilter -> rateLimit ->
                            provider -> providerRequestFilter -> messageContext] ->
           ProxyForwarder -> ProxyResponseHandler -> Response

Key components:

• GuardPipeline (guard-pipeline.ts): Configurable chain of request guards
• ProxySession (session.ts): Request context holder
• ProxyForwarder (forwarder.ts): Handles upstream API calls
• ProviderResolver (provider-selector.ts): Load balancing with weight/priority
• Format Converters (converters/): Bidirectional format translation

API Layer

• Proxy endpoints: /v1/messages, /v1/chat/completions, /v1/responses
• Management API: /api/actions/{module}/{action} - Auto-generated OpenAPI docs
• Docs: /api/actions/scalar (Scalar UI), /api/actions/docs (Swagger)

Code Conventions

• Path alias: @/ maps to ./src/
• Formatting: Biome (double quotes, trailing commas, 2-space indent, 100 char width)
• Exports: Prefer named exports over default exports
• i18n: Use next-intl for internationalization (5 languages: zh-CN, zh-TW, en, ja, ru)
• Testing: Unit tests in tests/unit/, integration in tests/integration/, source-adjacent tests in src/**/*.test.ts

Environment Variables

Critical variables (see .env.example for full list):

• ADMIN_TOKEN: Admin login token (required)
• DSN: PostgreSQL connection string
• REDIS_URL: Redis connection URL
• ENABLE_RATE_LIMIT: Toggle rate limiting
• SESSION_TTL: Session cache TTL (default 300s)
• AUTO_MIGRATE: Auto-run migrations on startup