CLAUDE.md Template: Go (Gin) + Supabase DB + Supabase Auth + Bun ORM Microservice

Overview

CLAUDE.md template for a Go (Gin) microservice that uses Supabase DB and Supabase Auth, paired with a Bun ORM microservice. This page provides a copyable CLAUDE.md template block and stack-specific guidance so you can drop it into Claude Code and generate production-ready code for the Go API, authentication flow, data access, and deployment patterns.

Direct answer: This CLAUDE.md Template yields a Go (Gin) API layer secured with Supabase Auth JWTs, backed by a Supabase Postgres DB, plus a Bun ORM microservice for data access, all wired for containerized deployment.

When to Use This CLAUDE.md Template

• You need a Go (Gin) REST API that authenticates with Supabase Auth and reads/writes to Supabase DB.
• You want a separate Bun ORM microservice (Node/TS) for specific data access patterns or integration points.
• You prefer a microservice architecture with clear boundaries: gin-api and bun-orm-service.
• You plan for Docker Compose or Kubernetes deployment and CI/CD pipelines.
• You want Claude Code to generate explicit, stack-specific code blocks and tests.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code; generate a production-ready Go (Gin) microservice that talks to a Supabase Postgres DB and uses Supabase Auth for authentication. Implement a Bun ORM microservice (Node/TS) for data access patterns, but keep the core API in Go. The output should be copy-pasteable into a CLAUDE.md file.

Architecture rules:
- Monorepo pattern with two services: gin-api (Go) and bun-orm-service (Node/TS).
- Communication via HTTP REST between services; avoid hard dependencies on internal endpoints.
- Use Supabase as the single source of truth for DB and authentication; verify JWT in gin-api per request.
- Environment variables provided via .env.template and CI secrets in production.
- Dockerized deployments with clear service boundaries; support docker-compose for local dev.
- Logging: structured JSON logs in Go and Node; use a common log format.
- Versioning: semantic versioning for images; tag references in deployment manifests.

File structure rules:
- gin-api/ contains the Go Gin application (handlers, middleware, models, repository).
- bun-orm-service/ contains the Bun ORM (Node/TS) backend with data access routes.
- docker-compose.yml wires both services and a proxied/secure config.
- .env.example provides necessary placeholders (do not commit secrets).

Authentication rules:
- gin-api validates the Supabase JWT on every request using the public keys from Supabase.
- Use RS256 tokens; verify 'sub', 'exp', and audience claims as configured in Supabase.
- Protect private endpoints; enforce role-based access if defined in Supabase.

Database rules:
- Connect to Supabase Postgres via DATABASE_URL; do not embed credentials in code.
- Use prepared statements or parameterized queries; avoid string concatenation for queries.
- Use connection pooling with sensible limits; handle PG errors gracefully.

Validation rules:
- Validate all inputs using Go validators for gin-api (e.g., go-playground/validator).
- Normalize and sanitize strings; reject malformed payloads early.

Security rules:
- Do not log raw secrets; mask tokens in logs.
- Use TLS in all external communications; avoid plaintext HTTP in production.
- Rotate credentials and secrets; store in environment vaults or CI secrets.

Testing rules:
- Unit tests for handlers and middleware; mock DB and auth layers.
- Integration tests for gin-api endpoints with a test Supabase instance or a mocked DB.
- End-to-end tests to cover auth flow, DB access, and Bun ORM microservice interactions.

Deployment rules:
- Dockerfiles for both services and a docker-compose.yml for local development.
- Kubernetes manifests or Helm charts for production deployments; include liveness/readiness probes.
- CI/CD steps to build, test, and push images to a registry; run security checks.

Things Claude must not do:
- Do not bypass Supabase Auth or issue your own tokens.
- Do not rely on unsafe eval or dynamic code generation that executes arbitrary code.
- Do not embed private keys or database credentials in code or config checked into git.
- Do not couple gin-api with Bun ORM in a way that hides service boundaries.

# End CLAUDE.md block

Recommended Project Structure

.
├── gin-api
│   ├── cmd
│   │   └── main.go
│   ├── internal
│   │   ├── handlers
│   │   │   └── v1
│   │   │       └── user.go
│   │   ├── middleware
│   │   │   └── auth.go
│   │   ├── models
│   │   │   └── user.go
│   │   └── repository
│   │       └── postgres.go
│   ├── config
│   │   └── config.go
│   ├── go.mod
│   └── go.sum
├── bun-orm-service
│   ├── src
│   │   ├── index.ts
│   │   ├── db.ts
│   │   └── routes.ts
│   ├── package.json
│   └── bunfig.toml
├── docker-compose.yml
├── .env.example
├── gin-api.Dockerfile
├── bun-orm.Dockerfile
└── README.md

Core Engineering Principles

• Single responsibility: gin-api handles HTTP API concerns; bun-orm-service handles data access.
• Explicit boundaries: avoid cross-service state sharing; communicate over REST with clear contracts.
• Secure by default: validate tokens, sanitize inputs, and minimize exposed surface area.
• Test-driven guidance: unit, integration, and deployment tests are required by design.
• Observability: structured logging, metrics, and traces for both Go and Node services.

Code Construction Rules

• Use Go modules; pin to minor versions compatible with Gin; avoid global state.
• Gin routing must be explicit; use middleware for auth and error handling.
• Env-based configuration; never hard-code secrets.
• Query construction must use parameterized statements (no string concatenation).
• Type safety: define strict DTOs for API requests/responses; avoid any implicit any in Bun ORM code.
• Keep Bun ORM service responsibilities focused on data access; do not embed business logic unrelated to data access.
• Logging should be JSON and include request IDs for traceability.
• Use migrations or seed scripts to manage DB schema changes.
• Do not rely on deprecated packages; prefer maintained libraries with active security patches.

Security and Production Rules

• Validate Supabase JWTs on every request to gin-api; verify claims and audience.
• Protect all endpoints; implement RBAC if configured in Supabase.
• Use HTTPS/TLS in all environments; disable debug endpoints in prod.
• Secrets management: store credentials in CI secrets or vaults, not in code.
• Container security: run as non-root, minimize image layers, and scan for vulnerabilities.

Testing Checklist

• Unit tests for handlers and middleware; mock external services and database access.
• Integration tests for gin-api endpoints with a test Supabase DB or mocks.
• End-to-end tests for auth flow and Bun ORM service interactions (where applicable).
• Security tests: JWT validation, token expiry, and role-based access checks.
• Deployment tests: Docker image builds, container startup, and load tests in CI.

Common Mistakes to Avoid

• Hard-coding credentials or keys in source code.
• Assuming Bun ORM can be embedded directly into a Go gin-api workflow; keep responsibilities separate.
• Skipping JWT validation or misconfiguring audience/issuer checks.
• Overly broad CORS allowances; keep origins restricted for production.
• Neglecting environment parity between dev, staging, and prod (DB URL, secrets, or feature flags).

FAQ

What does this CLAUDE.md Template generate?

A Go (Gin) API with Supabase DB/Auth integration and a Bun ORM microservice scaffold, ready for deployment.

Which stack does it target?

Go (Gin) API, Supabase Postgres DB, Supabase Auth, and Bun ORM microservice (Node/TS).

How do I run it locally?

Use docker-compose up to start both services; ensure .env.example is configured and copied to .env.

How is authentication enforced?

JWTs from Supabase are verified by gin-api middleware; tokens are validated against Supabase public keys.

Can I adapt this for other DBs?

Yes, but the template targets Supabase; switching DBs requires adapting the repository layer and connection setup.