# CLAUDE.md

## Project Context
Go HTTP API service. Router: chi or echo. Database: PostgreSQL with sqlc. Deployment: Docker.

## Code Style
- Follow Effective Go and Go Code Review Comments
- gofmt + goimports on all files
- No init() functions
- Exported types need godoc comments
- Use context.Context as first parameter on all service methods

## Architecture
```
cmd/server/main.go      — entry point
internal/
  handler/              — HTTP handlers (thin, call services)
  service/              — business logic
  repository/           — database access (sqlc generated)
  middleware/            — HTTP middleware
  model/                — domain types
pkg/                    — shared utilities (if any)
```

## Error Handling
- Use fmt.Errorf with %w for wrapping
- Custom error types with errors.As/errors.Is
- HTTP handlers return proper status codes
- Never log and return — do one or the other

## Database
- sqlc for type-safe queries (sqlc generate)
- Migrations with golang-migrate
- All queries in internal/repository/queries/
- Connection pooling with pgxpool

## Testing
- Table-driven tests
- testcontainers-go for integration tests
- httptest for handler tests
- go test ./... -race -cover before committing

## Docker
- Multi-stage build (builder + runtime)
- Non-root user in final image
- Health check at /healthz
- Graceful shutdown with signal handling

## Git
- Conventional commits: feat:, fix:, chore:
- Run go vet ./... before pushing