acc-server-manager/CLAUDE.md

CLAUDE.md

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

Development Commands

Building and Running

# 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

# 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

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

Setup and Configuration

# 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.