Backend coding conventions

Status: draft scaffold. Replace TODOs with real content. PH comparison links are signposts, not prescriptions — we adopt selectively.

PH analogue: posthog.com/handbook/engineering/conventions/backend-coding (their canonical doc, kept next to the code at PostHog/posthog:docs/published/handbook/engineering/conventions/backend-coding.md).

What already exists in this repo:

• docs/agents/backend-code-style.md — current Hono/core-api style notes (LLM-facing)
• docs/agents/database.md — Supabase/RLS/migration conventions
• apps/core-api/AGENTS.md — service-level guidance
• apps/learning-api/AGENTS.md — Python service guidance

This doc supersedes / consolidates those once filled in.

First principles

TODO. Things to articulate:

• What we optimize for (correctness vs throughput vs DX).
• When to add abstraction vs inline.
• Error handling philosophy.
• Boundaries between core-api, learning-api, Supabase functions.

Hono / core-api

TODO.

• Routing conventions, file structure.
• Validation (zod), error types.
• Auth surface (Supabase JWT verification).
• Logging / structured fields.

Python / learning-api

TODO.

• uv for dependency management (memory: never use pip on host)
• Module layout, FastAPI patterns.
• Async vs sync rules.

Supabase

TODO. Already partially at docs/agents/database.md. Pull authoritative parts here.

• Migration workflow.
• RLS defaults.
• Edge function vs core-api decision rule.

Open questions

TODO — capture as we draft.