lv8girl/AGENTS.md

AGENTS.md - lv8girl Project Guidelines

This document provides guidelines for AI agents working on the lv8girl project - a Go-based forum system.

Project Overview

lv8girl is a Go + Gin + SQLite forum system with user registration, posts, comments, likes, private messages, and admin dashboard.

Build & Development Commands

Basic Commands

# Install dependencies
go mod tidy

# Run the application
go run ./cmd/server

# Build binary
go build -o lv8girl ./cmd/server

# Run tests (if any)
go test ./...

# Run specific test
go test ./internal/services -v

# Test coverage
go test ./... -cover

Database Operations

# Database is automatically created at: data/lv8girl.db
# Auto-migration runs on application start

Code Quality

# Format code
go fmt ./...

# Vet code for suspicious constructs
go vet ./...

# Static analysis
go install honnef.co/go/tools/cmd/staticcheck@latest
staticcheck ./...

Code Style Guidelines

General Principles

• Follow Go standard conventions and effective Go guidelines
• Use layered architecture: Controllers → Services → Repositories → Models
• Keep functions small and focused (single responsibility)
• Prefer composition over inheritance
• Handle errors properly - never ignore them

Imports Organization

import (
    // Standard library
    "fmt"
    "time"
    "net/http"

    // Third-party packages
    "github.com/gin-gonic/gin"
    "gorm.io/gorm"

    // Local packages (project-specific)
    "lv8girl/internal/models"
    "lv8girl/internal/services"
)

Naming Conventions

• Packages: lowercase, single word, descriptive (e.g., controllers, services)
• Interfaces: -er suffix (e.g., Repository, Handler)
• Variables: camelCase, descriptive names
• Constants: PascalCase or ALL_CAPS for exported constants
• Methods: camelCase, verbs for actions (e.g., GetUserByID, CreatePost)

Error Handling

// Always check errors
if err != nil {
    return fmt.Errorf("context: %w", err)
}

// Use custom error types for domain errors
type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("%s: %s", e.Field, e.Message)
}

Types and Structs

// Use JSON tags for API responses
type User struct {
    ID        uint      `json:"id"`
    Username  string    `json:"username"`
    Email     string    `json:"email"`
    CreatedAt time.Time `json:"created_at"`
}

// Use GORM tags for database models
type Discussion struct {
    ID      uint   `gorm:"primaryKey" json:"id"`
    Title   string `gorm:"size:200;not null" json:"title"`
    Content string `gorm:"type:text;not null" json:"content"`
}

Function Signatures

// Return errors as last parameter
func GetUserByID(id uint) (*models.User, error)

// Use context for cancellation and timeouts
func GetUser(ctx context.Context, id uint) (*models.User, error)

// Receiver names should be short (1-2 letters)
func (c *Controller) HandleRequest(ctx *gin.Context)

Project Structure Patterns

cmd/server/main.go           # Application entry point
internal/config/             # Configuration management
internal/controllers/        # HTTP request handlers (Gin)
internal/services/          # Business logic layer
internal/repositories/       # Data access layer (GORM)
internal/models/            # Data models
internal/middleware/        # HTTP middleware
internal/routes/            # Route definitions
internal/utils/             # Utility functions

Controller Patterns

// Use dependency injection
type AuthController struct {
    authService *services.AuthService
}

func NewAuthController() *AuthController {
    return &AuthController{
        authService: services.NewAuthService(),
    }
}

// Handle HTTP requests with Gin
func (c *AuthController) Login(ctx *gin.Context) {
    // Parse input
    // Call service
    // Return response
}

Service Layer Patterns

// Services handle business logic
type AuthService struct {
    userRepo *repositories.UserRepository
}

func (s *AuthService) Login(login, password string) LoginResult {
    // Business logic
    // Call repositories
    // Return result
}

Repository Patterns

// Repositories handle database operations
type UserRepository struct {
    db *gorm.DB
}

func (r *UserRepository) FindByID(id uint) (*models.User, error) {
    var user models.User
    result := r.db.First(&user, id)
    return &user, result.Error
}

Testing Guidelines

// When adding tests, follow these patterns:
func TestUserService_CreateUser(t *testing.T) {
    // Arrange
    // Act  
    // Assert
}

// Use table-driven tests
func TestValidateUser(t *testing.T) {
    tests := []struct {
        name     string
        user     models.User
        expected error
    }{
        // test cases
    }
}

Security Considerations

• Never commit secrets (session keys, passwords)
• Use environment variables for sensitive configuration
• Validate all user input
• Use prepared statements (GORM handles this)
• Hash passwords with bcrypt/scrypt

Performance Guidelines

• Use connection pooling (GORM handles this)
• Implement pagination for lists
• Cache frequently accessed data
• Use indexes on frequently queried columns

Documentation

• Document exported functions and types
• Use clear, concise comments for complex logic
• Update README.md for new features
• Keep API documentation in sync with code

Common Tasks

Adding a New Feature

1. Add model in internal/models/
2. Add repository methods in internal/repositories/
3. Add service logic in internal/services/
4. Add controller in internal/controllers/
5. Add routes in internal/routes/routes.go
6. Add templates in templates/ (if needed)

Database Migrations

• Models are auto-migrated on startup
• For manual migrations, create migration files
• Test migrations before applying to production

API Endpoints

• Use RESTful conventions where appropriate
• Return appropriate HTTP status codes
• Use JSON for API responses
• Document API changes

Development Workflow

1. Before starting: Run go mod tidy to ensure dependencies are current
2. During development: Use go run ./cmd/server for testing
3. Before committing: Run go fmt ./... and go vet ./...
4. Testing: Write tests for new functionality
5. Documentation: Update relevant documentation

Project-Specific Notes

• Default admin credentials: admin / admin123
• Session secret is hardcoded in config - change for production
• Database path: data/lv8girl.db
• Server runs on port :8989 by default
• Uses Gin web framework with HTML templates
• Uses GORM with SQLite (no CGO required)

Troubleshooting

• Database issues: Check data/ directory permissions
• Import errors: Run go mod tidy
• Build errors: Ensure Go 1.21+ is installed
• Runtime errors: Check logs for detailed error messages

Resources

• Go Documentation
• Gin Framework
• GORM Documentation
• Effective Go