docs: documentation standards + party golden module (handoff hardening) - #472
Merged
Conversation
Establish the documentation foundations for the IT handoff. Arms docstring linters repo-wide and fully documents the party module in both stacks as the golden reference that the remaining modules will mirror. - Backend: enable Ruff `D` (Google convention) with a shrinking per-file-ignore rollout list; add `ErrorResponse` model + `error_response()` and `PAGINATED_QUERY_RESPONSES` helpers; fully docstring + OpenAPI the party module (summary, reachable error responses, request examples). - Frontend: add eslint-plugin-jsdoc (exports only, no type tags) with an opt-in rollout allowlist; fully document the party API domain + useServerTableState. - Agents: nested AGENTS.md (root/backend/frontend) with CLAUDE.md symlinks; migrate .claude/CLAUDE.md; document layering, naming, docstring conventions, and verification. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fan out the golden-module standard across account, auth, student, police, incident, location, and notification — Google docstrings on every public symbol, summary on every route, reachable-only error responses via the shared error_response()/PAGINATED_QUERY_RESPONSES helpers. Removes each module's per-file-ignore from the Ruff D rollout list; D is now enforced on all modules (only main.py and core/** remain pending). All 60 routes now have summaries. Note: the location router's autocomplete/place-details endpoints had a catch-all `except Exception` that re-wrapped typed exceptions (incl. 404/400) as a generic 500. Removed it so the typed exceptions propagate correctly and the documented responses are accurate — a small behavior fix (404/400 were previously masked). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Docstring all of src/core (auth, config, database, exceptions, types, and the utils: query, email, date, excel, phone, bcrypt) plus main.py. Removes the last rollout exemptions, so Ruff D now enforces docstrings across all of backend/src (only tests, migrations, and scripts remain exempt). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add TSDoc to every exported function/class/component/hook across the frontend: the remaining lib/api domains, lib utils/auth/config, components, contexts, and the staff/police/student route groups. Flip eslint-plugin-jsdoc from the opt-in allowlist to enforce on all of src/** (components/ui exempt). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- backend/README.md: architecture, module pattern, API docs (/docs, /redoc), common tasks (tests, migrations, dev scripts), verification. - frontend/README.md: App Router layout, the service/queries/types trio, route-access model, scripts, conventions. - Root README: new "Documentation & Architecture" section linking the sub-READMEs, AGENTS.md, the live API docs, the layer diagram, and a Notion TDD placeholder. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
naasanov
marked this pull request as ready for review
June 24, 2026 19:40
…into vidur/regis-track-limit
…party-registration into docs/handoff-documentation
…into docs/handoff-documentation
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Robust documentation for the IT handoff: IT is unfamiliar with the stack and will delegate fixes to AI agents, so we're standardizing docstrings, OpenAPI, and agent guidance. This is Session 1 of 4 (foundations + the golden reference module); the remaining sessions fan out the standard across all modules, then update the READMEs and Notion TDD.
Changes:
Drules (Google convention) repo-wide, with a shrinkingper-file-ignoresrollout list — undocumented areas are exempt until done, then removed one-by-one.ErrorResponsemodel +error_response()helper and a sharedPAGINATED_QUERY_RESPONSESconstant so error responses aren't re-typed per route.summaryon every route, reachable-only error responses, request examples oncreate_party.eslint-plugin-jsdoc(exports only, no type tags since the stack is typed) with an opt-in rollout allowlist.useServerTableStatehook.AGENTS.md(root/backend/frontend) withCLAUDE.mdsymlinks; migrated.claude/CLAUDE.md. Documents the strict layering, naming conventions, docstring standards (with examples + skip rules), and verification.All 10 pre-commit hooks pass repo-wide; the OpenAPI schema was verified to generate with the new summaries, examples, and error schemas.
🤖 Generated with Claude Code