Go (Fiber) + PostgreSQL + Custom JWT Middleware + GORM - CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md template provides a copyable Claude Code block for building a Go (Fiber) API backed by PostgreSQL using GORM, with a custom JWT middleware. It covers architecture rules, file structure, validation, security, testing, and deployment considerations for this stack.

The stack covered: Go (Fiber) web framework, PostgreSQL database, a custom JWT middleware for stateless authentication, and GORM as the ORM layer. Claude Code enforces concrete constraints and includes a ready-to-paste template tailored for this stack.

When to Use This CLAUDE.md Template

• Kick off a REST API with Fiber and PostgreSQL using GORM as the data layer.
• Enforce a security-first JWT-based authentication flow with a custom middleware.
• Prototype, validate, and deploy a production-like API with reproducible constraints.
• Generate a shareable CLAUDE.md block to onboard teammates quickly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are Claude Code. You provide an actionable CLAUDE.md template for a Go (Fiber) API backed by PostgreSQL, with a custom JWT middleware and GORM ORM. Your output should be copy-paste ready for developers.

Architecture Rules:
- Follow a clean, layered architecture: delivery (HTTP handlers), usecases (services), and repository (data access).
- Use dependency injection for DB connections and services.
- Keep business logic out of delivery layer; validate in the usecase layer.
- Treat PostgreSQL as the source of truth; migrations must be explicit and idempotent.
- Use GORM v2 for data access with explicit model tags and constraints.

File Structure Rules:
- cmd/api/main.go
- internal/config/
- internal/delivery/http/handlers.go
- internal/delivery/http/middleware/jwt.go
- internal/domain/models.go
- internal/repository/postgres/
- internal/service/auth/jwt.go
- migrations/
- go.mod, go.sum

Authentication Rules:
- Implement a custom JWT middleware for Fiber that validates HS256 tokens signed with a secret loaded from environment variables.
- Do not expose raw tokens in logs.
- Rotate secrets and provide a token revocation strategy (short-lived tokens + refresh tokens is acceptable).

Database Rules:
- Use PostgreSQL with GORM; define models with GORM tags and proper constraints.
- Use a migrations folder for all schema changes; avoid on-start migrations in production unless explicitly enabled.
- Always validate DB errors and roll back transactions when needed.

Validation Rules:
- Validate all incoming payloads using go-playground/validator.v10 in the usecase layer.
- Return concise, consistent error responses with error codes and field details.

Security Rules:
- Never log PII or secrets.
- Enforce TLS in production; store secrets in environment variables.
- Use prepared statements via GORM; avoid raw string concatenation for queries.

Testing Rules:
- Unit-test handlers and usecases; mock repository interfaces.
- Integration tests against a PostgreSQL test database; seed and clean up after tests.
- Include tests for JWT middleware (valid and invalid tokens).

Deployment Rules:
- Provide a Dockerfile and docker-compose for local development; migrations run during container startup when a flag is set.
- Use environment variables for DB connection, JWT secret, and app settings.
- Build with Go 1.20+; enable module-aware mode.

Things Claude must not do:
- Do not bypass migrations for production data.
- Do not log raw passwords or JWT secrets.
- Do not embed secrets in the CLAUDE.md output.

Recommended Project Structure

go-fiber-postgresql-custom-jwt-gorm-claude-md-template/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── database/
│   │   └── postgres.go
│   ├── delivery/
│   │   └── http/
│   │       ├── handlers.go
│   │       └── middleware.go
│   ├── domain/
│   │   └── models.go
│   ├── repository/
│   │   └── postgres/
│   │       └── repo.go
│   └── service/
│       └── auth/
│           └── jwt.go
├── migrations/
│   └── 001_initial.sql
├── go.mod
├── go.sum

Core Engineering Principles

• Explicitness: clear responsibilities and predictable control flow.
• Testability: code is easily unit-testable and supports integration tests with a test DB.
• Security by default: secure defaults, rotation of secrets, minimal privileges.
• Reliability: deterministic migrations and robust error handling.
• Observability: structured logging, metrics, and traceability in production.

Code Construction Rules

• Use Go modules; pin to Go 1.20+; keep dependencies minimal and explicit.
• Model definitions must use GORM v2 tags and PostgreSQL-compatible data types.
• JWT middleware must validate tokens and attach user claims to the request context.
• All business logic resides in usecases; delivery only handles request/response wiring.
• Environment-driven configuration; never hardcode credentials.
• Validate inputs with go-playground/validator in usecases; return structured errors.
• Do not bypass migrations; use explicit schema changes in migrations folder.

Security and Production Rules

• Store secrets in environment variables or a secret manager; do not commit them.
• Use TLS/HTTPS in production; enforce secure cookies for any session-based data.
• Limit JWT token lifetime and implement refresh tokens if necessary.
• Use least privilege roles for DB connections; use connection pools with sane limits.
• Audit logs for authentication events without exposing token contents.

Testing Checklist

• Unit tests for handlers and services with mocked repositories.
• Integration tests against a PostgreSQL test database; seed data and validate end-to-end flows.
• JWT middleware tests for valid, expired, and invalid tokens.
• Deployment smoke tests to verify migrations run and API endpoints respond correctly.

Common Mistakes to Avoid

• Hardcoding secrets or using insecure defaults in production builds.
• Relying on auto-migrate in production without versioned migrations.
• Embedding business logic in HTTP handlers; keep handlers thin and delegate to usecases.
• Forgetting to validate inputs before hitting the database.

FAQ