social-app/.trellis/spec/backend/quality-guidelines.md

Quality Guidelines

Code quality standards for backend development.

---

Overview

Backend quality gates are centered around:

1. Static checks (ruff, basedpyright) via pre-commit
2. Pytest suites under backend/tests
3. Layering and contract discipline from backend/AGENTS.md

Evidence:

• .pre-commit-config.yaml (basedpyright + ruff, scoped to ^backend/)
• pyproject.toml (pytest config, test paths, live marker)
• backend/AGENTS.md (layering, logging, error contract, DB and env rules)

---

Forbidden Patterns

1) Error swallowing

• Forbidden by project rule: do not catch/log and silently continue.
• Root rule source: AGENTS.md.

Legacy examples to avoid extending:

• backend/src/v1/users/dependencies.py (_verify_user_with_supabase) catches broad exceptions and returns None fallback.
• backend/src/services/base/service_interface.py (initialize_registered_services / close_registered_services) catches broad exceptions and continues lifecycle flow.

2) Runtime print() usage

• Backend runtime must use core.logging, not print().
• Rule source: backend/AGENTS.md.

3) Unstructured HTTP error contracts

• Business/API errors must not rely only on free-text detail; use stable code (+ optional params).
• Sources:
  • backend/AGENTS.md
  • docs/protocols/common/http-error-codes.md

4) Reading env by ad-hoc os.getenv in runtime

• Runtime configuration must go through core.config.settings.
• Source: backend/AGENTS.md and implementation in backend/src/core/config/settings.py.

---

Required Patterns

Layering discipline

• Use schema -> repository -> service flow.
• Repository: query/CRUD + flush; no transaction ownership.
• Service: authz/business rules + commit/rollback boundary.

Evidence:

• backend/src/v1/todo/repository.py vs backend/src/v1/todo/service.py
• backend/src/v1/schedule_items/repository.py vs backend/src/v1/schedule_items/service.py
• backend/src/core/db/session.py docs explicitly state caller (service) owns commit/rollback

Typed boundary models

• Prefer Pydantic models with strict extras handling for API/request contracts.
• Evidence across schemas:
  • backend/src/v1/todo/schemas.py
  • backend/src/v1/schedule_items/schemas.py
  • backend/src/v1/users/schemas.py

Protocol alignment

• If API contract changes (error codes/data formats), update corresponding docs/protocols/** docs in same change.
• Source: root AGENTS.md + backend rules.

---

Testing Requirements

Observed baseline:

• Unit tests: backend/tests/unit/**
• Integration tests: backend/tests/integration/**
• Live e2e tests separated by marker live: backend/tests/e2e/README-live.md

Pytest setup evidence:

• pyproject.toml
  • testpaths = ["backend/tests"]
  • markers = ["live: ..."]

Practical expectations for backend changes:

• Add/adjust tests for changed behavior where possible (especially contract/business logic).
• Keep live tests opt-in unless task explicitly requires real dependency runs.

---

Code Review Checklist

Use this checklist for backend PR review:

1. Layering
   • Router stays thin (backend/src/v1/*/router.py)
   • Service owns transaction and business decisions
   • Repository does not own commit/rollback
2. Error contract
   • Responses align with RFC7807 + stable code
   • New/changed codes reflected in docs/protocols/common/http-error-codes.md
3. Logging
   • Uses core.logging.get_logger
   • No raw sensitive values in logs
4. Config/secrets
   • Reads configuration via core.config.settings
   • No hardcoded secrets
5. Tests and checks
   • Relevant pytest scope updated if behavior changed
   • ruff + basedpyright remain passing for backend scope

---

Uncertainties (documented, not invented)

• Backend runtime still contains some legacy fallback exception patterns in specific infra/dependency paths (for example in backend/src/v1/users/dependencies.py fallback helper). New code should avoid expanding these patterns unless explicitly required.
• No dedicated, repository-wide automated rule currently enforces every layering guideline; enforcement is primarily pre-commit + review discipline.