skills.rest
palfish-t-i-u
palfish-t-i-uOFFICIAL
Explore all skills by this author →
GitHub

backend-conventions

Documents FastAPI backend architecture, route registration patterns, and deployment procedures for the PalFish GMV app.

1|Updated May 23, 2026
Search Tags:#debugging#fastapi#supabase#rbac#backend conventions#route registration#render deploy
One-click install
npx skills add https://github.com/palfish-t-i-u/palfish-t-i-u-h-th-ng-ver-2 --skill backend-conventions-palfish-t-i-u
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: backend-conventions
Source: https://github.com/palfish-t-i-u/palfish-t-i-u-h-th-ng-ver-2/tree/main/.claude/skills/backend-conventions
Command: npx skills add https://github.com/palfish-t-i-u/palfish-t-i-u-h-th-ng-ver-2 --skill backend-conventions-palfish-t-i-u

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Backend contributors risk silently breaking routes, leaking memory, or misconfiguring environments when working on the PalFish GMV FastAPI backend without knowing its architectural contract — most notably the 2026-06-19 indentation incident that silently dropped 10 routes. ## Core Features & Use Cases - Route Registration Contract: Documents the exact register_*_routes(app, _supabase) pattern, module-scope helper rules, and post-merge route count verification commands to catch silent 404s. - Operational Runbooks: Covers local dev startup on Windows, health checks, PostgREST schema cache fixes, Supabase client singleton usage, audit logging, sequential ID generation via RPC helpers, and Render deploys via scripts/deploy.sh. - Incident & Gotcha Knowledge: Records the singleton Supabase client memory leak fix, disabled legacy JWT keys, CORS regex requirements, RBAC role resolution order, and sandbox DingTalk isolation. - Use Case: After merging a PR touching activation_routes.py, run the Tier 1 route-count verification to confirm all 17 activation routes are still registered before deploying. ## Quick Start Ask the assistant to verify that all backend routes are correctly registered after your latest merge to main.py.

Frequently Asked Questions about backend-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new route module to a FastAPI app?▼

Create a module exporting one register_*_routes(app, supabase_factory) function, import it in main.py, and call it after FastAPI() instantiation but before startup handlers. Then verify registration by counting routes via python -c "import main".

Why do FastAPI routes return 404 after a merge?▼

A helper function accidentally indented inside a register_*_routes function causes subsequent @app.route decorators to nest inside it and never execute. FastAPI raises no warning, so run a route count check after every merge touching registration code.

Should I create a new Supabase client per request in FastAPI?▼

No. Use the process-wide singleton factory; creating a new client per call leaked roughly 150MB per hour of unclosed httpx pools and OOM-crashed the 512MB Render instance every few hours.

How do I fix PostgREST schema cache errors in Supabase?▼

Run NOTIFY pgrst, 'reload schema'; in the Supabase SQL Editor. This resolves pgrst204 or schema cache errors that appear after applying a migration.

When should I not use this backend conventions guide?▼

Skip it for frontend React/Vite work, Supabase migrations, or the separate pf-revenue repository, which has a different codebase and deployment process.

Related Skills

Explore More Software Engineering Skills→
gabrielnsmntogabrielnsmnto
3

db-supabase-setup

Guides interactive setup of Supabase projects with CLI configuration, extensions, and migrations.

Community
Intermediate
shekerkammashekerkamma

canary

Monitor live production deploys for console errors, performance regressions, and page failures.

Community
Advanced
Jason-hub-starJason-hub-star

be-fe-model-sync

Synchronize backend model changes to frontend TypeScript types and API clients.

Community
Advanced
n8n-ion8n-io
421

n8n-error-handling

Wire n8n node error outputs to structured webhook responses with correct HTTP status codes.

Official
Advanced