Backend Conventions

Stack

• Hono + TypeScript (Node entry in src/index.ts).
• Zod for validation with @hono/zod-validator.
• Supabase service clients via utils/supabase.ts.

Routing layout

• Routes live in src/routes and are mounted in src/index.ts.
• Auth guards are middleware-based (requireAuth).
• Use zValidator at route boundaries for json/query/form payloads.

Middleware and context

• Global middleware order: CORS, Sentry transaction, auth.
• Auth middleware sets Context vars: profile, authenticated, serviceRole, posthogClient.
• Use requireAuth for protected endpoints; use requireAutomationAdminKey for admin automation.

Error handling

• Prefer throwing HTTPException for non-OK responses.
• Let global error handler emit 500 with a generic message; avoid leaking internals.
• Log unexpected errors with console.error and Sentry via the global handler.

Services and utils

• Business logic lives in src/services; routes should stay thin.
• Shared helpers in src/utils; request/response types in src/types.

Type safety

• Prefer shared types from @studyflash-ai/types and @studyflash-ai/common.
• Avoid any/unsafe casts when possible; validate untrusted input with Zod.