# CLAUDE.md

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

## Development Commands

### Building and Running
```bash
# Build the main application
go build -o api.exe cmd/api/main.go

# Build with hot reload (requires air)
go install github.com/cosmtrek/air@latest
air

# Run the built binary
./api.exe

# Build migration utility
go build -o acc-server-migration.exe cmd/migrate/main.go
```

### Testing
```bash
# Run all tests
go test ./...

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

# Run specific test package
go test ./tests/unit/service/
go test ./tests/unit/controller/
go test ./tests/unit/repository/
```

### Documentation
```bash
# Generate Swagger documentation (if swag is installed)
swag init -g cmd/api/main.go
```

### Setup and Configuration
```bash
# Generate security configuration (Windows PowerShell)
.\scripts\generate-secrets.ps1

# Deploy (requires configuration)
.\scripts\deploy.ps1
```

## Architecture Overview

This is a Go-based web application for managing Assetto Corsa Competizione (ACC) dedicated servers on Windows. The architecture follows a layered approach:

### Core Layers
- **cmd/**: Application entry points (main.go for API server, migrate/main.go for migrations)
- **local/**: Core application code organized by architectural layer
  - **api/**: HTTP route definitions and API setup
  - **controller/**: HTTP request handlers (config, membership, server, service_control, steam_2fa, system)
  - **service/**: Business logic layer (server management, Steam integration, Windows services)
  - **repository/**: Data access layer with GORM ORM
  - **model/**: Data models and structures
  - **middleware/**: HTTP middleware (auth, security, logging)
  - **utl/**: Utilities organized by function (cache, command execution, JWT, logging, etc.)

### Key Components

#### Dependency Injection
Uses `go.uber.org/dig` for dependency injection. Main dependencies are set up in `cmd/api/main.go`.

#### Database
- SQLite with GORM ORM
- Database migrations in `local/migrations/`
- Models support UUID primary keys

#### Authentication & Security
- JWT-based authentication with two token types (regular and "open")
- Comprehensive security middleware stack including rate limiting, input sanitization, CORS
- Encrypted credential storage for Steam integration

#### Server Management
- Windows service integration via NSSM
- Steam integration for server installation/updates via SteamCMD
- Interactive command execution for Steam 2FA
- Firewall management
- Configuration file generation and management

#### Logging
- Custom logging system with multiple levels (debug, info, warn, error)
- Request logging middleware
- Structured logging with categories

### Testing Structure
- Unit tests in `tests/unit/` organized by layer (controller, service, repository)
- Test helpers and mocks in `tests/` directory
- Uses standard Go testing with mocks for external dependencies

### External Dependencies
- **Fiber v2**: Web framework
- **GORM**: ORM for database operations
- **SteamCMD**: External tool for Steam server management (configured via STEAMCMD_PATH env var)
- **NSSM**: Windows service management (configured via NSSM_PATH env var)

### Configuration
- Environment variables for external tool paths and configuration
- JWT secrets generated via setup scripts
- CORS configuration with configurable allowed origins
- Default port 3000 (configurable via PORT env var)

## Important Notes

### Windows-Specific Features
This application is designed specifically for Windows and includes:
- Windows service management integration
- PowerShell script execution
- Windows-specific path handling
- Firewall rule management

### Steam Integration
The Steam 2FA implementation (`local/controller/steam_2fa.go`, `local/model/steam_2fa.go`) provides interactive Steam authentication for automated server management.