CLAUDE.md Template: Hono Server + Neon Postgres + Clerk Auth + Drizzle ORM High-Concurrency API

Overview

A CLAUDE.md Template for building a high-concurrency API using Hono server, Neon Postgres, Clerk authentication, and Drizzle ORM. This template provides Claude Code instructions to paste into CLAUDE.md and land with a production-ready structure for a Node.js/TypeScript environment.

Stack covered: Hono (edge-friendly runtime), Neon Postgres (managed Postgres), Clerk (auth), and Drizzle ORM (type-safe data access).

When to Use This CLAUDE.md Template

• When you need a high-concurrency API with low warmup latency on the edge.
• When you require a secure, scalable auth layer with Clerk.
• When you want type-safe DB access through Drizzle ORM against Neon Postgres.
• When you must maintain clear architecture boundaries and testability.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: API Architect for a high-concurrency Hono server backed by Neon Postgres, with Clerk authentication and Drizzle ORM.
Architecture rules:
- Stateless microservice pattern
- Separate concerns: auth, data access, API gateway, business logic
- Use Neon DB connection pooling
- Use Drizzle ORM for type-safe queries
File structure rules:
- Keep src/server/main.ts entry
- Use src/routes/api.ts for all endpoints
- Use db/drizzle for ORM setup
Authentication rules:
- Clerk authentication via cookie + session; token-based for API clients
- Use Clerk middleware in Hono
Database rules:
- Neon Postgres with TLS
- Use Drizzle migrations
- Enforce constraints: unique, not null, foreign keys
Validation rules:
- Request payload validation with schema checks
- Global input sanitization
Security rules:
- Do not log full credentials
- Do not bypass TLS
- Do not bypass auth for protected endpoints
Testing rules:
- Unit tests for services layer
- Integration tests for DB access and Clerk auth
- E2E tests for high-concurrency path
Deployment rules:
- Use Docker image with Node runtime
- Deploy to Vercel/Cloud Run as serverless
Things Claude must not do:
- Do not generate insecure secrets
- Do not bypass authentication
- Do not assume privileged DB access

Recommended Project Structure

my-hono-project/
├── src
│   ├── server
│   │   └── main.ts
│   ├── routes
│   │   └── api.ts
│   ├── middleware
│   └── services
├── db
│   ├── drizzle
│   │   ├── index.ts
│   │   └── schema.ts
│   └── migrations
├── config
│   ├── clerk.ts
│   ├── neon.ts
│   └── drizzle.ts
├── tests
│   ├── unit
│   └── integration
├── .env.example
├── package.json
├── tsconfig.json

Core Engineering Principles

• Type-safety and explicit contracts via Drizzle and TypeScript
• Clear separation of concerns across auth, data, and API layers
• Stateless design with deterministic side effects
• Resilient error handling and observability in concurrency scenarios
• Infrastructure-as-code-minded deployment patterns

Code Construction Rules

• Use Hono Router to define routes; keep business logic in services
• Protect endpoints with Clerk middleware; issue short-lived tokens for clients
• Access Neon Postgres via Drizzle ORM; prefer prepared statements and migrations
• Validate all inputs with strict type guards and schema checks
• Centralize configuration via env vars; never hard-code secrets
• Favor idempotent operations for writable endpoints

Security and Production Rules

• Enforce TLS to Neon Postgres and HTTPS for API endpoints
• Do not log sensitive data; redact tokens and secrets
• Rotate Clerk keys and database credentials periodically
• Enable rate limiting and circuit breakers on high-traffic paths
• Audit trails and non-repudiation for auth events

Testing Checklist

• Unit tests for all service functions and validators
• Integration tests for DB access, migrations, and Drizzle models
• Auth flow tests with Clerk sign-in/sign-out and session management
• Load/integration tests to verify high-concurrency paths
• End-to-end tests of critical user journeys

Common Mistakes to Avoid

• Owning too much state in the server; avoid shared mutable globals
• Ignoring DB migrations during deployments
• Under-protecting endpoints or misconfiguring Clerk guards
• Over-relying on client-side validation without server checks

FAQ

• Q: What is this CLAUDE.md Template for?
• A: A copyable CLAUDE.md Template page for a high-concurrency Hono + Neon + Clerk + Drizzle stack.
• Q: Which stack is covered?
• A: Hono server, Neon Postgres, Clerk authentication, and Drizzle ORM.
• Q: Can I adapt the template to existing projects?
• A: Yes; it provides paste-ready CLAUDE.md and a stack-specific project structure.
• Q: Does it include deployment guidance?
• A: It includes deployment and testing guidance; adapt to your infra.