Owner Abhi

Implementation delta: where docs and code differ

This file lists gaps between the PRD, the reviewed TRD, and what we shipped. Use it when you wonder “was this on purpose?” For day-to-day API truth, use OpenAPI, test-document, and the comment routes/schemas under src/api/av1/comment/.

How to read the status words

  • Matches: code and doc agree; nothing to do.
  • On purpose: we chose to ship differently; the doc is older or narrower.
  • Open: still needs a product or engineering decision.
  • Bug: code should be fixed to match an agreed doc (none listed here as open bugs; use your tracker if one appears).

Compared to the PRD

  • Human tiers A / B / C are still named loosely in the PRD. In code we map them to system admin, admin, and editor until product locks final names (see PRD open questions).
  • Tier C cells marked TBD in the PRD are treated as deny until we model them.
  • AI may only create comments; it cannot change, resolve, reopen, or delete. Nobody can edit a comment written by AI.
  • Body: PRD mentioned plain text first; we ship plain text and Plate JSON, up to 10,000 characters, so rich comments fit.
  • Delete: We keep both a deleted status and the soft-delete flag so a future “show deleted” view is easier than the oldest TRD line that relied on the flag alone.
  • Audit: PRD asked for transitions to be traceable. We have a comment_audit collection and the repository writes rows on create, body edit, resolve, reopen, and delete. Automated tests that assert every field in those rows are still thin. Repository behavior: comment row commits first; audit insert is best-effort (failure is logged, API still returns success for the mutation) so clients are not told OPERATION_FAILED after the comment already changed. Optional later improvement: Mongo multi-document transaction if the cluster supports it.
  • No separate author_id: we use created_by like other entities. AI agents are normal user rows.
  • No author_role stored on the comment: permission checks use the current JWT role, not a snapshot at post time.
  • Resolver time and user are not on the main comment row; they live in audit rows for resolve and reopen.
  • Count badge and stronger delete text for “delete someone else’s comment” match PRD spirit.
  • Notifications and who triggers AI are still open product topics; phase 1 does not include notifications.

Compared to the reviewed TRD

Matches

  • Collection name comments, not docket_comments.
  • Target is content_type + content_id, not a single docket_id field.
  • Mongo object id per comment (many comments per docket).
  • author_type stored on the row (human vs AI).
  • author_role, resolved_at, and resolved_by removed from the model (as in the struck TRD lines).
  • body_type text vs Plate; indexes on list pattern match the intent.
  • Same URL prefix and the same eight operations (create, list, counts, get, patch, resolve, reopen, delete).
  • AI uses the normal create endpoint with a token that marks the caller as AI.
  • Counts use repeated query parameters for many ids.

On purpose

  • Body length in the TRD was 2,000 characters; shipped 10,000 for Plate JSON.
  • List filter by author_type exists in the API even though the TRD deferred it; it is supported because the field is stored.
  • Response includes author_name so the UI does not guess names from ids alone.
  • Permission matrix lives in Python (and a small copy in the web app), not in a Mongo “settings” document.
  • Admin UI is a side column next to the docket preview, not only a floating modal; still “attached to the docket,” not a random dialog.
  • DELETED as a status in addition to the soft-delete flag: helps a later “deleted comments” view. The TRD once preferred the flag only; product can confirm here and close the item.

Open

  • Whether we ever drop the extra DELETED status and rely only on the flag (would need a migration and UI agreement).
  • Whether author_type filter stays long term or gets tightened to match the shortest TRD wording.

Compared to test document

The test document lists test cases; the code should match. If you change behavior, update test-document in the same change.

Watch list

  • Add tests that read audit documents if you want stronger guarantees.
  • New content types need validation and tests like docket has today.
  • If product adds a new role tier, update comment_permissions.py, test-document, OpenAPI-facing schemas, and this file in one go.

Compared to OpenAPI and tests

The HTTP contract is defined in FastAPI route handlers and Pydantic schemas (surfaced as OpenAPI). test-document lists case IDs; release-checklist lists pre-ship gates. If behavior and Swagger disagree, fix code or schema; do not maintain a parallel prose spec file.

Short action list

  1. Product: confirm tier names and any PRD matrix cell you want different from today’s admin / editor / system admin map.
  2. Engineering: close gaps in release-checklist (API contract: HTTP 200 + JSON error.code where missing) and add tests keyed from test-document.
  3. Engineering: optional table-driven test for every permission helper cell.
  4. Product: decide “deleted status + flag” vs “flag only” and update TRD addendum or this file when closed.
  5. Docs: if the TRD gets a formal v2, copy the “on purpose” bullets there so new readers are not confused by old numbers in the frozen TRD body.