CLAUDE.md Template for Hono Server + Supabase DB/Auth + PostgREST Client Proxy Engine

Overview

CLAUDE.md Template for Hono Server plus Supabase DB and Supabase Auth with a PostgREST Client Proxy Engine. This page provides a copyable CLAUDE.md template that developers can paste into Claude Code to generate a robust edge API scaffold and governance rules for this stack.

When to Use This CLAUDE.md Template

• You are building an edge API on Hono and need to connect to a Supabase DB and Supabase Auth.
• You require a PostgREST client proxy to translate REST calls to SQL with RBAC controls.
• You want a copyable CLAUDE.md template to enforce architecture, security, and testing from the start.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Claude Code acts as a governance and automation assistant for a Hono based API layer backed by Supabase DB and Auth with a PostgREST client proxy Engine
Architecture rules: Keep edge friendly, minimal dependencies, prefer RESTful endpoints via PostgREST, ensure stateless operations, and define RBAC at the API layer
File structure rules: place code under src, db, auth, proxy, tests; avoid global state; document every rule
Authentication rules: use Supabase Auth tokens, verify JWTs on each request, enforce role based access in routes
Database rules: use Supabase DB with row level security, ensure minimal exposure of tables, apply policies by role
Validation rules: validate input at boundary, enforce schema, reject unexpected fields
Security rules: rotate keys, never log secrets, use TLS, implement anti replay protections
Testing rules: unit tests for handlers, integration tests for proxy flows, end to end tests for auth and DB access
Deployment rules: deploy via edge friendly stack, keep env vars secure, use CI to run tests
Things Claude must not do: bypass auth, expose DB keys, bypass validation, write to memory without persistence

Recommended Project Structure

hono-supabase-auth-postgrest
├── src
│   ├── server.ts
│   ├── routes
│   │   └── proxy.ts
│   ├── middleware
│   │   └── auth.ts
│   └── lib
│       └── db.ts
├── db
│   ├── migrations
│   └── seeds
├── infra
│   ├── docker
│   └── terraform

Core Engineering Principles

• Define clear boundaries between edge routing, auth, and data access
• Prefer stateless handlers with explicit lifecycle for edge CPU efficiency
• Automate security checks and testing in CI
• Document architecture decisions with concise rules

Code Construction Rules

• Do not mix client side and server side concerns in same module
• Do not bypass auth checks in proxy routes
• Do not hard code secrets in code or config files
• Do use proper TypeScript types for request and response payloads

Security and Production Rules

• Enforce JWT validation at the edge for all requests
• Limit DB access via PostgREST client proxy with RBAC policies
• Rotate keys and enforce TLS everywhere
• Audit log access to Proxied endpoints

Testing Checklist

• Unit tests for auth and header parsing
• Integration tests for proxy to Supabase DB endpoints
• End to end tests for auth flows and data reads
• Deployment tests for edge and DB connection

Common Mistakes to Avoid

• Assuming PostgREST proxy handles auth automatically
• Overexposing DB endpoints without policies
• Using insecure storage for secrets

FAQ

Q What is this CLAUDE.md Template for

It provides a copyable CLAUDE.md template to implement an edge API using Hono, Supabase DB and Auth, and a PostgREST client proxy engine.

Q Which stack does this template target

Hono Server plus Supabase DB and Supabase Auth with a PostgREST client proxy, optimized for Claude Code automation.

Q Can I paste this into Claude Code directly

Yes. The included CLAUDE.md block is copyable and designed to be pasted into Claude Code to generate code and governance rules.

Q What are the deployment considerations

Ensure edge deployment with Hono edge, secure Supabase keys, and proper PostgREST endpoint exposure with RBAC rules.