# 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.