CLAUDE.md Template: Go (Echo) + MongoDB + Firebase Auth Integration + Mongo-Go-Driver

Overview

Direct answer: This CLAUDE.md Template provides a copyable CLAUDE.md block and a complete Go (Echo) API layout that uses MongoDB via the Mongo-Go-Driver and Firebase Auth integration. It is stack-specific for a production-ready API.

It targets developers building an API with Echo, authenticating users via Firebase Auth tokens, and persisting data in MongoDB using the official MongoDB Go driver. The template enforces secure patterns, proper validation, and clean architecture suitable for production deployments.

When to Use This CLAUDE.md Template

• You are building a RESTful API in Go using Echo as the HTTP framework.
• You require Firebase Auth for authentication and token verification on protected routes.
• You store data in MongoDB and access it via the official Mongo-Go-Driver.
• You want a copyable CLAUDE.md that codifies architecture, security, and testing rules for this stack.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a software engineering assistant that outputs a ready-to-paste CLAUDE.md template for a Go (Echo) API with MongoDB and Firebase Auth using the Mongo-Go-Driver. Produce concrete, runnable instructions without introducing non-stack technologies.

Architecture rules:
- Use Echo as the HTTP router; separate layers: handler -> service -> repository.
- Access MongoDB through the official Mongo-Go-Driver; inject the client via DI.
- Validate and sanitize all inputs; use go-playground/validator where applicable.
- Verify Firebase ID tokens on protected routes with Firebase Admin SDK.
- Do not access the database without a proper context and a timeout.

File structure rules:
- cmd/server/main.go
- internal/config/config.go
- internal/db/mongo.go
- internal/auth/firebase.go
- internal/middleware/auth.go
- internal/handler/user.go
- internal/service/user.go
- internal/repository/user.go
- internal/routes/routes.go
- go.mod, go.sum

Authentication rules:
- Tokens must be validated against Firebase Admin; reject missing or expired tokens.
- Attach per-request user identity after validation for downstream services.

Database rules:
- Use Mongo-Go-Driver with proper URI handling and timeouts.
- Enforce index on users.email and users.createdAt where appropriate.
- Do not log sensitive user fields (emails, hashes).

Validation rules:
- Use struct tags and validator.v10 for payloads (e.g., email, required fields).
- Return 400 for invalid payloads; 401 for unauthorized when token is invalid.

Security rules:
- Do not log passwords or tokens; avoid stack traces in responses.
- Retrieve secrets from environment variables; do not hard-code.
- Enforce TLS in production; expose only necessary endpoints.

Testing rules:
- Unit tests for handlers and services using httptest and testify.
- Integration tests to verify DB interactions with a test MongoDB instance.
- Mock Firebase Admin interactions where possible.

Deployment rules:
- Provide a Dockerfile for a static Go binary; include a docker-compose example for local testing.
- Build with CGO_ENABLED=0 for portability when appropriate.

Things Claude must not do:
- Do not bypass authentication or validation.
- Do not introduce hard-coded credentials or secrets.
- Do not propose non-Go runtimes or non-Go libraries.

Recommended Project Structure

go-echo-mongodb-firebase-auth-mongo-driver/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── db/
│   │   └── mongo.go
│   ├── auth/
│   │   └── firebase.go
│   ├── middleware/
│   │   └── auth.go
│   ├── handler/
│   │   └── user.go
│   ├── service/
│   │   └── user.go
│   ├── repository/
│   │   └── user.go
│   │   
│   └── routes/
│       └── routes.go
├── go.mod

Core Engineering Principles

• Explicitness over magic: clear interfaces and contracts between layers.
• Type safety and validation: enforce payload shapes and token integrity early.
• Fail-fast with meaningful errors: surface actionable messages to clients and logs.
• Separation of concerns: handlers, services, and repositories are distinct.
• Security by default: never log sensitive data; verify tokens server-side; use TLS and env secrets.
• Observability: structured logging, request IDs, and metrics hooks.

Code Construction Rules

• Use Go modules; pin versions; avoid global state.
• Context-aware: pass context with timeouts to DB calls and external services.
• Validation-first: validate all inputs before business logic runs.
• Token verification: validate Firebase ID tokens on protected routes; extract user claims for services.
• Error handling: unify error responses with codes and messages; never expose internals.
• Modular tests: write unit tests for services and handlers; integration tests for DB and auth flows.

Security and Production Rules

• Firebase Admin SDK used for token verification; tokens must be current and issued for your project.
• MongoDB access via a dedicated service account; least privilege roles.
• Secret management: fetch DB URI and Firebase credentials from environment or secret store.
• TLS termination in production; disable verbose error messages in responses.
• Audit and rotate credentials; avoid logging sensitive values.

Testing Checklist

• Unit tests for handlers with httptest and mocks for services.
• Integration tests for DB access using a test MongoDB deployment.
• Token verification tests: valid, expired, missing tokens.
• Deployment verification: ensure Dockerfile builds and runs in production-like env.

Common Mistakes to Avoid

• Relying on client-provided IDs without server-side validation.
• Implementing custom auth that bypasses Firebase token verification.
• Forgetting to set timeouts on DB calls or to cancel contexts on errors.
• Storing secrets in code or logs.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable CLAUDE.md block and a production-ready Go (Echo) API structure with MongoDB and Firebase Auth integration using the Mongo-Go-Driver.
• Which stack does this template target? Go (Echo) + MongoDB (Mongo-Go-Driver) + Firebase Auth integration.
• How do I verify Firebase tokens in Echo? Use the Firebase Admin SDK to validate ID tokens in middleware and attach user claims to the request context.
• How should data access be implemented? Repository layer uses go.mongodb.org/mongo-driver with proper timeouts and indexes (e.g., users.email).
• Where can I start with testing? Use httptest for handlers, mock services, and run integration tests against a test MongoDB instance.