gorest: Instructions file for Claude Code

CLAUDE.md

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

Authoritative references

This repo already ships detailed agent docs. Read these before making changes — they are the source of truth and far more complete than this file:

• AGENTS.md — build/lint/test commands, code style, import aliases, layer responsibilities, controller↔handler 1:1 map, config/db/middleware/service APIs.
• llms.txt — machine-readable interface describing repo purpose, capabilities, and constraints.
• .agents/skills/<name>/SKILL.md — task-specific workflow guides (test-runner, ci-orchestrator, migration-helper, config-loader-helper, etc.).

Files to NEVER read or modify

Per .gitignore (and AGENTS.md), these contain secrets, keys, or generated noise. Do not open, read, or edit them:

• .env and any *.log (includes log.txt), *.bak
• keys/, tmp/, .build/, .vscode/, vendor/
• coverage.txt, coverage_0.txt
• pri*key*.pem, pub*key*.pem
• crosscompile*.sh

Common commands

source setTestEnv.sh                           # required before running tests locally
go test -v -cover ./...                        # all tests
go test -v -run TestHashPass ./lib/...         # single test function
golangci-lint run ./...                        # lint (CI uses v2.12.2, --timeout 5m)
go vet -v ./... && go build -v ./...           # vet + build

CI additionally runs gosec, govulncheck, and cross-platform go vet/build across linux/darwin/windows × amd64/arm64. Tests need env vars (CI uses secrets; locally setTestEnv.sh).

Architecture (the big picture)

gorest is a reusable Go module (github.com/pilinux/gorest), not just an app. It is both a library of auth/crypto/middleware/db primitives and two example apps that wire them together. Requires Go 1.25.0+ (go.mod declares go 1.25.0; CI tests against Go 1.25.x and 1.26.x).

Request flow follows a strict layered pipeline:

controller/  → thin: bind request, call handler, renderer.Render(c, data, status)
handler/     → business logic + validation; returns (model.HTTPResponse, int)
service/     → shared utilities: auth, JWT blacklist, email (Postmark), crypto, 2FA
database/    → connection management for RDBMS (GORM), Redis (radix), MongoDB
config/      → loads .env → Configuration struct; IsX() feature toggles gate everything