ERP/AGENTS.md

ERP System Agent Guidelines

This document provides instructions for coding agents working on the ERP System repository.

1. Build, Lint, and Test

Build

To build the application:

go build -o erp_system main.go

To run the application locally:

go run main.go

The server defaults to port 1337.

Test

Run all tests:

go test ./...

Run a specific test package:

go test ./internal/handlers/...

Run a single specific test function:

# Pattern: go test -v <package_path> -run <TestNameRegex>
go test -v ./internal/handlers -run TestLoginSubmit

Lint / Verify

Run standard Go vetting:

go vet ./...

Format code (always run before committing):

go fmt ./...

2. Code Style & Conventions

General

• Language: Go 1.25.6+
• Formatting: Strictly adhere to gofmt standards.
• Naming:
  • Use PascalCase for exported structs, fields, and functions.
  • Use camelCase for unexported (private) identifiers.
  • Keep variable names short but descriptive (e.g., req vs r is fine if context is clear, but userRequest is better for complex scopes).

Project Structure

• main.go: Application entry point, router setup, dependency injection.
• internal/: Private application code.
  • database/: DB initialization and helpers.
  • handlers/: HTTP handlers.
  • models/: Data structs and business logic/DB queries.
  • middleware/: HTTP middleware (Auth, etc.).
• templates/: HTML templates (server-side rendered).

Imports

Group imports into three blocks separated by a newline:

1. Standard library (e.g., "net/http", "os")
2. Third-party packages (e.g., "github.com/gorilla/sessions")
3. Internal project packages (e.g., "erp_system/internal/models")

Example:

import (
	"log"
	"net/http"

	"github.com/gorilla/sessions"

	"erp_system/internal/models"
)

Error Handling

• Explicit Checks: Always check errors. if err != nil { ... }.
• Handlers: Use http.Error(w, err.Error(), http.Status...) to return errors to the client.
• Logging: Log critical errors on the server side using log.Printf or similar before returning HTTP 500.

HTTP & Routing

• Use Go's standard net/http ServeMux with Go 1.22+ routing patterns (e.g., mux.Handle("GET /path/{id}", ...)).
• HTMX: The application uses HTMX.
  • Check for HX-Request header to differentiate full page loads vs partials.
  • Use HX-Redirect header for client-side redirection when handling HTMX requests.
  • Render partial templates when appropriate.

Database

• Use internal/models for all database interactions.
• Pass the database connection (*sql.DB) or a wrapping struct to handlers via dependency injection (see Handler struct in main.go).

3. Cursor / Copilot Rules

(No specific Cursor or Copilot rules found in the repository yet. Adhere to the conventions above.)