AnCao/CLAUDE.md

CLAUDE.md

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

Project Overview

AnKao is a Go web application built using the Gin framework. The project follows a clean architecture pattern with clear separation of concerns and is designed to support database integration.

Architecture

Request Flow

1. HTTP requests arrive at the Gin server running on port 8080
2. Requests pass through Gin's default middleware (Logger, Recovery) and custom middleware
3. The Gin router matches routes and directs requests to appropriate handlers
4. Handlers (in internal/handlers/) process requests using *gin.Context and return JSON responses

Middleware Pattern

Middleware in Gin uses the gin.HandlerFunc pattern:

func MiddlewareName() gin.HandlerFunc {
    return func(c *gin.Context) {
        // Pre-processing
        c.Next()
        // Post-processing
    }
}

Middleware is registered in main.go:15 using r.Use().

Module Structure

• main.go - Application entry point, server configuration and routing setup
• internal/handlers/ - HTTP request handlers, all use *gin.Context and return JSON responses
• internal/middleware/ - Gin middleware chain (currently: custom logger)
• internal/models/ - Data models (directory exists, ready for database models)
• pkg/config/ - Configuration management (directory exists but not yet populated)

Common Commands

Development

# Run the server
go run main.go

# Install/update dependencies
go mod tidy

# Format code
go fmt ./...

# Vet code for common issues
go vet ./...

Building

# Build binary to bin/server
go build -o bin/server.exe main.go

# Run built binary (Windows)
.\bin\server.exe

# Run built binary (Unix)
./bin/server

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests in a specific package
go test ./internal/handlers/

# Run tests with verbose output
go test -v ./...

Key Implementation Details

• Framework: Using Gin v1.11.0
• Server Port: :8080 (configured in main.go:22)
• Handler Signature: All handlers use func(c *gin.Context) pattern
• JSON Response: Use c.JSON() method with gin.H{} or structs
• Import Paths: Use module name ankao (defined in go.mod)
• Route Registration: Routes are registered in main.go using r.GET(), r.POST(), etc.
• Middleware: Applied globally with r.Use() or per-route with route grouping

Adding New Features

Adding a New Handler

1. Create handler function in internal/handlers/ with signature func(c *gin.Context)
2. Use c.JSON() to return responses
3. Register route in main.go (e.g., r.GET("/path", handlers.YourHandler))

Adding Middleware

1. Create middleware in internal/middleware/ returning gin.HandlerFunc
2. Apply globally with r.Use(middleware.YourMiddleware()) or to route groups

Database Integration

The project is ready for database integration:

• Add models in internal/models/
• Consider using GORM or similar ORM
• Add database initialization in main.go or separate package