# 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:
```go
func MiddlewareName() gin.HandlerFunc {
    return func(c *gin.Context) {
        // Pre-processing
        c.Next()
        // Post-processing
    }
}
```
Middleware is registered in [main.go:15](main.go#L15) 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
```bash
# 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
```bash
# 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
```bash
# 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](main.go#L22))
- **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](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](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