backend-dev-guidelines

FastAPI endpoints should use short-lived SQLAlchemy 2.0 Core sessions that close after each request, paired with ON CONFLICT clauses to ensure idempotent writes. This prevents session leaks and guarantees safe retries without duplicate data.

Temporal workflows must be deterministic: avoid non-deterministic calls, use Pydantic DTOs for all I/O, and keep database operations outside the workflow logic. SQLAlchemy 2.0 Core queries must complete within activity timeouts to prevent workflow hangs.

Gmail and Sheets API integrations require credential management, retry logic for rate limits, and idempotent operations to handle partial failures. Wrap API calls in try-catch blocks and log failures for debugging without exposing credentials.

Pre-flight deployment checks include verifying environment variables, confirming database connection pooling limits match Fly.io constraints, testing Temporal workflow connectivity, and validating API authentication. This reduces production surprises and rollback risk.

Tests fail when workflows contain non-deterministic code, database sessions persist across test runs, or Pydantic DTOs omit required fields for Temporal serialization. Isolate workflow logic, reset session state between tests, and validate DTO schemas.

Yes. Supabase PostgreSQL works with SQLAlchemy 2.0 Core and supports the ON CONFLICT syntax needed for idempotent writes. Configure connection pooling carefully and use short-lived sessions to avoid hitting Supabase connection limits.