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.

FAQ