Hono + MongoDB Atlas + Custom Cookie Auth + Mongoose Edge Build - CLAUDE.md Template

Overview

The CLAUDE.md template describes a practical approach for building an edge API using Hono, with MongoDB Atlas as the database, a custom cookie-based authentication mechanism, and Mongoose for ODM on the edge. This is a copyable CLAUDE.md template page designed for Claude Code to generate scaffolding, wiring, and tests for this specific stack. It emphasizes an edge-first architecture while keeping database access secure and observable.

When to Use This CLAUDE.md Template

• You are building a lightweight edge API with Hono that talks to MongoDB Atlas.
• You want cookie-based authentication with httpOnly, Secure cookies in production.
• You need Mongoose as the ODM on an edge-friendly deployment.
• You plan to deploy to an edge platform (e.g., Cloudflare Workers) and require a clean project layout.
• You need a ready-to-paste CLAUDE.md template block for rapid iteration and sharing.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code helping implement an edge API using Hono, MongoDB Atlas, Custom Cookie Auth, and Mongoose Edge Build. Provide a clean, maintainable, and secure scaffold.

Architecture rules:
- Edge-first design with Hono Router and minimal middleware.
- MongoDB Atlas as the canonical database; access via Mongoose ODM.
- Stateless API with cookie-based authentication; session state stored in httpOnly cookies.
- Layered structure: routes, models, services, config, and tests.
- Environment-driven configuration; no hard-coded credentials.
- Code must be deployable to a true edge environment (e.g., Cloudflare Workers) with an ESModule build.

File structure rules:
- Use a src/ directory with clear separation: routes/, models/, services/, middleware/, config/, db/.
- Each route file should export a Hono.Handler and be unit-testable.
- Keep model schemas in src/models/; keep DB initialization in src/db/connection.ts.
- Include a dedicated tests/ directory with at least unit tests for models and integration tests for routes.
- Use a single entry point at src/app.ts and a minimal bootstrap in src/server.ts (or index.ts for ESModule builds).

Authentication rules:
- Use custom cookie authentication with httpOnly, Secure (in production), and SameSite=Strict.
- Cookie name: sessionId; sign cookies with a server-side secret and validate on each request.
- Store only session identifiers in the cookie; do not place user data in cookies.
- Implement middleware to validate the session on protected routes; refresh the session as needed.
- Do not expose stack traces or raw errors to clients.

Database rules:
- Connect to MongoDB Atlas via a secure URI in MONGODB_URI from the environment.
- Use Mongoose for ODM; define models in src/models/ with proper validation.
- Create appropriate indexes for common queries (e.g., users.email).
- Use TLS/SSL and enforce TLS connections from the edge to Atlas.
- Do not perform unparameterized queries; rely on Mongoose validation.

Validation rules:
- Validate external input with a stack-consistent schema (e.g., Zod) before reaching deeply into business logic.
- Validate request bodies, query parameters, and route params.
- Enforce server-side validation for all mutations; return clear error messages without leaking internals.

Security rules:
- Use httpOnly, Secure cookies; SameSite=Strict; enable CSRF protection for state-changing requests if forms exist.
- Do not log sensitive data; redact or avoid logging cookies and connection strings.
- Regularly rotate secrets and authenticate sessions using signed cookies.
- Disable verbose error responses in production; use a generic 500 message.

Testing rules:
- Unit tests for models and utilities; integration tests for routes using a test MongoDB Atlas database or in-memory replacements.
- Use a test runner (e.g., Vitest) and mocks for external services.
- Include end-to-end tests that exercise the login flow and protected endpoints.

Deployment rules:
- Prepare a minimal WASM-friendly ESModule bundle suitable for edge environments.
- Use a deployment tool compatible with Hono (e.g., wrangler for Cloudflare Workers) to deploy to the edge.
- Ensure environment variables are provided securely (e.g., MONGODB_URI, COOKIE_SECRET).
- Roll out first to a staging worker and run smoke tests before production.

Things Claude must not do:
- Do not hard-code credentials or secrets in the codebase.
- Do not bypass input validation or security checks.
- Do not store sessions in memory on the edge; use signed cookies and server-side validation.
- Do not rely on global mutable state across requests.
- Do not use deprecated Atlas connection strings or insecure TLS defaults.

---

End of CLAUDE.md template block. You can customize the environment variables and file paths to fit your repository.

Recommended Project Structure

project-root/
├─ src/
│  ├─ routes/
│  │  ├─ index.ts         # public routes
│  │  ├─ auth.ts          # login/logout/session endpoints
│  │  └─ user.ts          # user CRUD and profile endpoints
│  ├─ models/
│  │  └─ user.ts          # Mongoose schema for users
│  ├─ services/
│  │  └─ auth.ts          # authentication helpers
│  ├─ middleware/
│  │  └─ cookies.ts       # cookie parsing and session validation
│  ├─ config/
│  │  └─ index.ts         # environment and app config
│  ├─ db/
│  │  └─ connection.ts    # Mongoose connection to MongoDB Atlas
│  ├─ app.ts                 # Hono app and routes mounting
│  └─ server.ts              # entry point for local dev or edge wrapper
├─ tests/
│  ├─ auth.test.ts
│  └─ user.test.ts
├─ .env.example               # sample environment variables
├─ package.json
├─ tsconfig.json
├─ wrangler.toml               # Cloudflare Wrangler config for edge deploy

Core Engineering Principles

• Edge-first design with clear separation of concerns.
• Explicit, typed contracts for all inputs and outputs.
• Secure by default: httpOnly cookies, TLS, minimal surface area.
• Observability: structured logs, metrics, and health checks.
• Deterministic behavior: idempotent operations and deterministic error handling.

Code Construction Rules

• Models live under src/models/ with Mongoose schemas and validators.
• Routes live under src/routes/ and export a Hono.Handler for easy composition.
• Authentication uses custom cookies; do not rely on in-memory sessions.
• Environment variables govern secrets; never commit secrets.
• Use a centralized config module to read MONGODB_URI, COOKIE_SECRET, and NODE_ENV.
• All requests are validated against a schema before business logic runs.

Security and Production Rules

• Cookies are httpOnly, Secure in production, and SameSite=Strict.
• All database operations are validated through Mongoose and input schemas.
• Atlas IP whitelisting and TLS are enforced; never connect with the default insecure mode.
• Error handling hides internal details; log privately and surface generic messages to clients.
• Implement CSRF protection for state-changing endpoints when forms are used.

Testing Checklist

• Unit tests for models with Mongoose validation.
• Integration tests for authentication flow and protected routes.
• End-to-end tests simulating edge deployment environment.
• Tests run against a test MongoDB Atlas database or in-memory substitutes.
• Static analysis and type checks run in CI.

Common Mistakes to Avoid

• Storing too much data or sensitive details in cookies.
• Skipping input validation or using untrusted data directly in queries.
• Using in-memory sessions or global mutable state on the edge.
• Exposing detailed error messages in production.

Related implementation resources: CLAUDE.md Template: SvelteKit + TimescaleDB + Custom Token Session + Prisma ORM Pipeline, AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps, and RBAC matrices with clear permission inheritance in production AI systems.

FAQ