Backend Development Guidelines

This document outlines the development standards and best practices for Flexus backend services.

Technology Stack

• Language: Python 3.11+
• GraphQL: Strawberry GraphQL
• Database: PostgreSQL with Prisma ORM
• Cache: Redis for sessions and pub/sub
• Testing: pytest with async support

Code Style Standards

Error Handling

async def create_task(input: TaskInput) -> TaskOutput:
  try:
      task = await prisma.task.create(data)
      if not task:
          console.error("TASK_CREATE_FAILED", input)
          raise ValueError("Failed to create task")
      return TaskOutput.from_prisma(task)
  except Exception as e:
      console.error("TASK_CREATE_ERROR", e, input)
      raise

# DON'T DO THIS
async def create_task(input: TaskInput) -> TaskOutput:
  task = await prisma.task.create(data)
  if task:  # Silent failure!
      return TaskOutput.from_prisma(task)

For complete guidelines, see the existing AGENTS.md file in flexus_backend/.

API Development

All GraphQL operations follow these patterns:

Authentication

fuser_id, sid, internal_flags = await dig_out_sesh(info, is_websocket=False)

Authorization

has_permission = await check_group_permission(fuser_id, fgroup_id, "member")
if not has_permission:
    raise PermissionError("Insufficient permissions")

Audit Logging

await create_audit_record(
    audit_op="CREATE",
    table_name="flexus_task",
    record_id=task.task_id,
    fuser_id=fuser_id
)