Gin Go + MySQL + OAuth2 Auth0 Integration with Ent ORM — CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md Template provides a ready-to-paste Claude Code block and project blueprint for building a Go (Gin) API with MySQL using Ent ORM and OAuth 2.0 authentication via Auth0. It targets Clean Architecture and production-grade constraints.

The stack covered: Go, Gin, MySQL, Auth0 OAuth2, Ent ORM, with Claude Code guidance for structuring code, authentication, data access, validation, and deployment.

When to Use This CLAUDE.md Template

• When you are building a REST API in Go using Gin.
• When you want Ent ORM to model MySQL schema and migrations.
• When you use Auth0 for OAuth2 authentication.
• When you want a Claude Code blueprint to paste into CLAUDE.md for a production-grade API.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Backend API service in Go using Gin, MySQL, Auth0 OAuth2, and Ent ORM.
Architecture rules: Use Clean Architecture with entities, use cases, interface adapters, and frameworks; enforce strict package boundaries and DI.
File structure rules: Keep a lean top level; group by command, config, server, domain, infrastructure; Ent schemas live under ent/schema.
Authentication rules: Implement OAuth2 via Auth0; validate JWTs using Auth0 JWKS; require audience and issuer checks; rotate keys as needed.
Database rules: Use MySQL as the source of truth; model with Ent; run migrations in development and CI; avoid raw SQL without a purpose.
Validation rules: Validate input payloads with a validator; return 400 on validation errors with field details.
Security rules: Do not log sensitive data; disable default credentials exposure; require TLS; enforce CORS with sensible origins; protect endpoints with JWT validation.
Testing rules: Unit tests for domain and use cases; integration tests against a test MySQL container; test Auth0 tokens; CI runs tests on push.
Deployment rules: Dockerfile with multi stage build; docker-compose for local dev; minimal Kubernetes manifests; env vars loaded from a secure store; health checks enabled.
Things Claude must not do: Do not generate code that bypasses auth checks; do not mutate global state; do not embed secrets; do not use non idiomatic patterns; do not integrate non-Go ORMs beyond Ent.

Recommended Project Structure

.
├── cmd
│   └── api
│       └── main.go
├── internal
│   ├── config
│   │   └── config.go
│   ├── server
│   │   ├── router.go
│   │   └── server.go
│   ├── auth
│   │   └── oauth.go
│   ├── persistence
│   │   ├── mysql.go
│   │   └── ent
│   │       ├── ent.go
│   │       └── schema
│   │           └── user.go
│   └── domain
│       └── model.go
├── ent
│   ├── ent.go
│   └── schema
│       └── user.go
├── go.mod
└── go.sum

Core Engineering Principles

• Explicit contracts: use interfaces to define boundaries between layers.
• Single responsibility: each package has a clear, narrow purpose.
• Testable by design: enable unit and integration tests with minimal wiring.
• Observability: structured logging, tracing, and metrics hooks from day one.
• Security first: treat secrets as external, validate tokens, and enforce TLS.

Code Construction Rules

• Use Ent for MySQL modeling and migrations; generate schemas under ent/schema.
• Gin routers should be thin; handlers call use cases via interfaces.
• JWT validation must rely on Auth0 issuer and JWKS; check audience and scope as needed.
• Validation must fail fast with clear field error details.
• Environment-based configuration; no hard coded secrets.
• Prefer context propagation; cancel on request end.
• Do not bypass migrations or perform schema changes at runtime in production.

Security and Production Rules

• Enable TLS; reject plaintext HTTP in production.
• JWT access tokens validated against Auth0 JWKS; verify issuer and audience.
• Do not log JWT tokens or secrets; mask sensitive fields.
• Configure CORS to allow only known frontend domains.
• Store DB credentials and OAuth secrets in a secure vault; load at startup.

Testing Checklist

• Unit tests for domain logic and use cases with mocked Ent clients.
• Integration tests that spin a test MySQL database and validate Ent interactions.
• End-to-end tests for the OAuth2 flow using mock Auth0 tokens.
• CI pipelines run lint, unit tests, and integration tests; image builds are reproducible.
• Deployment tests include health checks and simple rollback scenarios.

Common Mistakes to Avoid

• Not validating JWTs or misconfiguring Auth0 issuer/audience.
• Treating Ent migrations as optional or skipping schema validation.
• Embedding secrets in code or logs; not using a secret manager.
• Overusing global state or non idiomatic Go patterns.
• Ignoring context cancellation leading to resource leaks.

FAQ

What is the goal of this CLAUDE.md Template

Provide a paste-ready Claude Code block and architecture blueprint for Gin Go API with Ent ORM and Auth0 OAuth2 integration.

Which ORM is used

Ent ORM for MySQL modeling and migrations; do not replace with other ORMs.

How is authentication handled

OAuth2 with Auth0; JWTs are validated against Auth0 JWKS with issuer and audience checks.

Is deployment guidance included

Yes; Dockerfile, docker-compose examples, and basic Kubernetes manifests are provided.

What is the recommended project layout

A lean Go project with cmd, internal, and ent directories organized around Gin, Ent schemas, and auth.

FAQ

Further questions about this template are covered in the above items. For more examples see the CLAUDE.md Templates collection.