From e9e0d6960a28a029b7521daabe988910a93debdc Mon Sep 17 00:00:00 2001
From: Abhimanyu Saharan <desk.abhimanyu@gmail.com>
Date: Thu, 12 Feb 2026 08:16:29 +0000
Subject: [PATCH] docs(backend): clarify auth/error-handling via docstrings

---
 backend/app/api/deps.py            | 18 +++++++++++++++++-
 backend/app/core/agent_auth.py     | 15 ++++++++++++++-
 backend/app/core/auth.py           | 17 ++++++++++++++++-
 backend/app/core/error_handling.py | 21 ++++++++++++++++++++-
 4 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py
index dfe623e6..ea4958f9 100644
--- a/backend/app/api/deps.py
+++ b/backend/app/api/deps.py
@@ -1,4 +1,20 @@
-"""Reusable FastAPI dependencies for auth and board/task access."""
+"""Reusable FastAPI dependencies for auth and board/task access.
+
+These dependencies are the main "policy wiring" layer for the API.
+
+They:
+- resolve the authenticated actor (admin user vs agent)
+- enforce organization/board access rules
+- provide common "load or 404" helpers (board/task)
+
+Why this exists:
+- Keeping authorization logic centralized makes it easier to reason about (and
+  audit) permissions as the API surface grows.
+- Some routes allow either admin users or agents; others require user auth.
+
+If you're adding a new endpoint, prefer composing from these dependencies instead
+of re-implementing permission checks in the router.
+"""
 
 from __future__ import annotations
 
diff --git a/backend/app/core/agent_auth.py b/backend/app/core/agent_auth.py
index 0d3fbb2d..1bd2b7eb 100644
--- a/backend/app/core/agent_auth.py
+++ b/backend/app/core/agent_auth.py
@@ -1,4 +1,17 @@
-"""Agent authentication helpers for token-backed API access."""
+"""Agent authentication helpers for token-backed API access.
+
+This module is used for *agent-originated* API calls (as opposed to human users).
+
+Key ideas:
+- Agents authenticate with an opaque token presented as `X-Agent-Token: <token>`.
+- For convenience, some deployments may also allow `Authorization: Bearer <token>`
+  for agents (controlled by caller/dependency).
+- To reduce write-amplification, we only touch `Agent.last_seen_at` at a fixed
+  interval and we avoid touching it for safe/read-only HTTP methods.
+
+This is intentionally separate from user authentication (Clerk/local bearer token)
+so we can evolve agent policy independently.
+"""
 
 from __future__ import annotations
 
diff --git a/backend/app/core/auth.py b/backend/app/core/auth.py
index 14decaf9..256e2bd8 100644
--- a/backend/app/core/auth.py
+++ b/backend/app/core/auth.py
@@ -1,4 +1,19 @@
-"""User authentication helpers for Clerk and local-token auth modes."""
+"""User authentication helpers for Clerk and local-token auth modes.
+
+This module resolves an authenticated *user* from inbound HTTP requests.
+
+Auth modes:
+- `local`: a single shared bearer token (`LOCAL_AUTH_TOKEN`) for self-hosted
+  deployments.
+- `clerk`: Clerk JWT authentication for multi-user deployments.
+
+The public surface area is the `get_auth_context*` dependencies, which return an
+`AuthContext` used across API routers.
+
+Notes:
+- This file documents *why* some choices exist (e.g. claim extraction fallbacks)
+  so maintainers can safely modify auth behavior later.
+"""
 
 from __future__ import annotations
 
diff --git a/backend/app/core/error_handling.py b/backend/app/core/error_handling.py
index 810f65e7..e2c0890f 100644
--- a/backend/app/core/error_handling.py
+++ b/backend/app/core/error_handling.py
@@ -1,4 +1,23 @@
-"""Global exception handlers and request-id middleware for FastAPI."""
+"""Global exception handlers and request-id middleware for FastAPI.
+
+This module standardizes two operational behaviors:
+
+1) **Request IDs**
+   - Every response includes an `X-Request-Id` header.
+   - Clients may supply their own request id; otherwise we generate one.
+   - The request id is propagated into logs via context vars.
+
+2) **Error responses**
+   - Errors are returned as JSON with a stable top-level shape:
+     `{ "detail": ..., "request_id": ... }`
+   - Validation errors (`422`) return structured field errors.
+   - Unhandled errors are logged at ERROR and return a generic 500.
+
+Design notes:
+- The request-id middleware is installed *outermost* so it runs even when other
+  middleware returns early.
+- Health endpoints are excluded from request logs by default to reduce noise.
+"""
 
 from __future__ import annotations