base/CLAUDE.md

CLAUDE.md

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

Project Overview

This is an AI development scaffolding project with a Go backend (go-zero) and React frontend (shadcn/ui). It provides a foundation for building full-stack applications with user management, authentication, and profile functionality.

Project Structure

.
├── backend/              # Go + go-zero + GORM backend
│   ├── api/              # API definition files (.api)
│   ├── internal/
│   │   ├── config/       # Configuration structures
│   │   ├── handler/      # HTTP handlers (grouped by feature)
│   │   ├── logic/        # Business logic (grouped by feature)
│   │   ├── middleware/   # CORS, Auth, Logging middleware
│   │   ├── svc/          # Service context (DB, config, middleware)
│   │   └── types/        # Request/response types (auto-generated)
│   ├── model/            # GORM entity models and data access
│   └── tests/            # Test standards documentation
└── frontend/react-shadcn/pc/   # React + Vite + shadcn/ui frontend
    ├── src/
    │   ├── components/   # UI components and layout
    │   ├── contexts/     # React contexts (AuthContext)
    │   ├── pages/        # Page components
    │   ├── services/     # API client
    │   └── types/        # TypeScript type definitions
    └── vite.config.ts    # Vite config with @/ alias

Backend Development

Build and Run

cd backend

# Run the server (requires MySQL)
go run base.go -f etc/base-api.yaml

# Run tests
go test ./...
go test ./internal/logic/user/...     # Run specific package tests
go test -v ./internal/logic/user/...  # Verbose output

# Generate code from API definitions (requires goctl)
goctl api go -api base.api -dir .

Architecture

go-zero Framework: The backend uses go-zero with the following conventions:

• API Definitions: Defined in *.api files using goctl syntax. Main entry: base.api
• Handler-Logic Pattern: Handlers parse requests and delegate to Logic structs
• Service Context (internal/svc/servicecontext.go): Holds shared resources (DB connection, config, middleware)
• Code Generation: internal/types/types.go and internal/handler/routes.go are auto-generated by goctl

Authentication Flow:

• JWT tokens issued on login/register
• Auth middleware validates Bearer tokens and injects user context
• Context keys: userId, username, email

Database (GORM):

• Models in model/ package with entity + model files
• Auto-migration on startup in servicecontext.go
• Supports MySQL (primary) and SQLite (testing)

API Structure

Base path: /api/v1

Group	Middleware	Endpoints
auth	Cors, Log	POST /register, /login, /refresh
user	Cors, Log, Auth	CRUD /user, /users
profile	Cors, Log, Auth	GET/PUT /profile/me, POST /profile/password

Frontend Development

Build and Run

cd frontend/react-shadcn/pc

# Install dependencies
npm install

# Development server (http://localhost:5173)
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Lint
npm run lint

Architecture

Tech Stack: React 19, TypeScript, Vite, Tailwind CSS v4, shadcn/ui components

Key Conventions:

• Path alias @/ maps to src/
• Environment variable: VITE_API_BASE_URL (defaults to http://localhost:8888/api/v1)
• Custom UI components in src/components/ui/ (Button, Card, Input, Modal, Table)

Authentication:

• AuthContext manages global auth state
• JWT stored in localStorage with key token
• ProtectedRoute component guards authenticated routes
• Auth header: Authorization: Bearer <token>

API Client (src/services/api.ts):

• Singleton apiClient class
• Auto-attaches auth headers from localStorage
• Methods organized by feature: auth, user management, profile

Testing Standards

Backend Testing

Each module follows the test flow: Create → Query → Update → Verify Update → List → Delete → Verify Delete

Test files use SQLite in-memory database for isolation. Example test structure:

func TestCreateUserLogic(t *testing.T) {
    // Setup SQLite DB
    // Create service context with test DB
    // Execute logic
    // Verify results
}

API Testing with curl

See backend/tests/USER_MODULE_TEST_STANDARD.md for detailed curl examples.

Quick test flow:

BASE_URL="http://localhost:8888/api/v1"

# 1. Register
POST /register

# 2. Get token, then call authenticated endpoints
GET /profile/me -H "Authorization: Bearer <token>"

Configuration

Backend (etc/base-api.yaml)

Name: base-api
Host: 0.0.0.0
Port: 8888
MySQL:
  DSN: "user:pass@tcp(host:port)/dbname?charset=utf8mb4&parseTime=true&loc=Local"

Frontend (.env or environment)

VITE_API_BASE_URL=http://localhost:8888/api/v1

AI Development Resources

• go-zero AI Context: https://github.com/zeromicro/ai-context
• shadcn/ui LLMs.txt: https://ui.shadcn.com/llms.txt
• zero-skills: https://github.com/zeromicro/zero-skills