[Hardening] Correct stale documentation: recording architecture, DB roles, stack versions

claude-bot commented

2026-07-14 19:51:04 +00:00

Collaborator

Context

Several load-bearing docs describe a system that no longer exists. Since CLAUDE.md files steer both humans and coding agents, stale claims actively cause wrong implementations.

Motivation

Four concrete divergences (all verified against current code):

(a) Recording architecture marked "not yet implemented" — it shipped. Root CLAUDE.md ("Recording architecture") says the audio pipeline is a target design with the bot still uploading a finished transcript, and describes a single mixed mono MP3. Reality:

POST /api/bot/sessions/{session_id}/audio exists (webapp/backend/app/routers/bot.py:657-707) and queues the process_audio Celery task (:698-705).
The bot records per-speaker 16 kHz WAV tracks plus a speakers.json into a per-session dir on audio_temp and calls the endpoint via post_audio_tracks (bot/questboard_bot/cogs/recording.py:595); the endpoint docstring (bot.py:666-672) confirms the per-speaker design, transcribed per speaker and merged into an attributed transcript — not the documented mono-MP3 → single-file Whisper flow.

(b) DB role claims are aspirational. Root CLAUDE.md and webapp/CLAUDE.md describe a DML-only questboard app user; in reality the app user is the entrypoint superuser. The privilege enforcement itself is tracked in the "[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql" issue in this milestone — align the doc wording with that issue's outcome (and drop webapp/CLAUDE.md's reference to init.sql, which that issue deletes).

(c) Frontend stack versions are stale. webapp/CLAUDE.md:20 claims "React 18, Vite 6, Tailwind 3, react-router-dom 6". webapp/frontend/package.json has: react 19.2.7, react-router-dom 7.15.0, eslint 10.7.0, tailwindcss 4.3.2, vite 8.1.4.

(d) Dockerfile comments contradict the base image. Section headers at Dockerfile:14 ("Backend / Worker / Beat (Python 3.12)") and :97 ("Bot (Python 3.12 + FFmpeg)") say Python 3.12, but both stages build FROM python:3.14-slim (:16, :99). Root CLAUDE.md also states Python 3.12 for both components.

Fix / Spec

Rewrite the root CLAUDE.md "Recording architecture" section to describe the shipped flow: bot captures per-speaker audio → writes 16 kHz WAVs + speakers.json to a per-session dir on the audio_temp volume → POST /api/bot/sessions/{session_id}/audio with the dir path → Celery process_audio transcribes each speaker via the remote Whisper endpoint, merges an attributed transcript, summarises, saves, notifies the bot. Remove the "not yet implemented" status block and the mono-MP3 wording.
Update the DB-user wording in root CLAUDE.md and webapp/CLAUDE.md to match the DB-privileges hardening issue: state the two-role model as enforced-by-init-script (or, if that issue hasn't merged yet, as "enforced from vX.X; earlier installs see docs/OPERATIONS.md"). Remove the init.sql mention from webapp/CLAUDE.md.
Fix webapp/CLAUDE.md:20 to the actual versions (read them from webapp/frontend/package.json at edit time rather than copying from this issue).
Align the Python-version comments at Dockerfile:14 and :97 (and the root CLAUDE.md Python claims) with whatever the CI/image Python version-alignment decision is. A dedicated issue on Python version alignment is planned for the v3.4.0 milestone (none filed at the time of writing — link it here once it exists); if it is still undecided when this issue is picked up, set the comments to match the current base image (3.14) and note the pending decision.

Acceptance criteria

A fresh reader of root CLAUDE.md gets the real recording flow (per-speaker WAV tracks, /audio endpoint, Celery pipeline) with no "not yet implemented" marker.
No doc claims a DML-only app user as a present-tense fact until it is true; wording references the enforcement issue/runbook.
webapp/CLAUDE.md stack table matches package.json majors; no reference to init.sql remains.
Dockerfile header comments match the actual base image version.

References

Root CLAUDE.md ("Recording architecture", "Shared infrastructure", repo-structure Python claims)
webapp/CLAUDE.md:20 (stack table); webapp/frontend/package.json:15/:18/:27/:30/:31
webapp/backend/app/routers/bot.py:657-707 (shipped audio endpoint), bot/questboard_bot/cogs/recording.py:523-595 (per-speaker pipeline)
Dockerfile:14/:16/:97/:99
Related: "[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql" (this milestone)

Filed from the July 2026 full-project review.

## Context Several load-bearing docs describe a system that no longer exists. Since `CLAUDE.md` files steer both humans and coding agents, stale claims actively cause wrong implementations. ## Motivation Four concrete divergences (all verified against current code): **(a) Recording architecture marked "not yet implemented" — it shipped.** Root `CLAUDE.md` ("Recording architecture") says the audio pipeline is a target design with the bot still uploading a finished transcript, and describes a **single mixed mono MP3**. Reality: - `POST /api/bot/sessions/{session_id}/audio` exists (`webapp/backend/app/routers/bot.py:657-707`) and queues the `process_audio` Celery task (`:698-705`). - The bot records **per-speaker 16 kHz WAV tracks plus a `speakers.json`** into a per-session dir on `audio_temp` and calls the endpoint via `post_audio_tracks` (`bot/questboard_bot/cogs/recording.py:595`); the endpoint docstring (`bot.py:666-672`) confirms the per-speaker design, transcribed per speaker and merged into an attributed transcript — not the documented mono-MP3 → single-file Whisper flow. **(b) DB role claims are aspirational.** Root `CLAUDE.md` and `webapp/CLAUDE.md` describe a DML-only `questboard` app user; in reality the app user is the entrypoint superuser. The privilege enforcement itself is tracked in the "[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql" issue in this milestone — align the doc wording with that issue's outcome (and drop `webapp/CLAUDE.md`'s reference to `init.sql`, which that issue deletes). **(c) Frontend stack versions are stale.** `webapp/CLAUDE.md:20` claims "React 18, Vite 6, Tailwind 3, react-router-dom 6". `webapp/frontend/package.json` has: react 19.2.7, react-router-dom 7.15.0, eslint 10.7.0, tailwindcss 4.3.2, vite 8.1.4. **(d) Dockerfile comments contradict the base image.** Section headers at `Dockerfile:14` ("Backend / Worker / Beat (Python 3.12)") and `:97` ("Bot (Python 3.12 + FFmpeg)") say Python 3.12, but both stages build `FROM python:3.14-slim` (`:16`, `:99`). Root `CLAUDE.md` also states Python 3.12 for both components. ## Fix / Spec 1. Rewrite the root `CLAUDE.md` "Recording architecture" section to describe the shipped flow: bot captures per-speaker audio → writes 16 kHz WAVs + `speakers.json` to a per-session dir on the `audio_temp` volume → `POST /api/bot/sessions/{session_id}/audio` with the dir path → Celery `process_audio` transcribes each speaker via the remote Whisper endpoint, merges an attributed transcript, summarises, saves, notifies the bot. Remove the "not yet implemented" status block and the mono-MP3 wording. 2. Update the DB-user wording in root `CLAUDE.md` and `webapp/CLAUDE.md` to match the DB-privileges hardening issue: state the two-role model as enforced-by-init-script (or, if that issue hasn't merged yet, as "enforced from vX.X; earlier installs see docs/OPERATIONS.md"). Remove the `init.sql` mention from `webapp/CLAUDE.md`. 3. Fix `webapp/CLAUDE.md:20` to the actual versions (read them from `webapp/frontend/package.json` at edit time rather than copying from this issue). 4. Align the Python-version comments at `Dockerfile:14` and `:97` (and the root `CLAUDE.md` Python claims) with whatever the CI/image Python version-alignment decision is. A dedicated issue on Python version alignment is planned for the v3.4.0 milestone (none filed at the time of writing — link it here once it exists); if it is still undecided when this issue is picked up, set the comments to match the current base image (3.14) and note the pending decision. ## Acceptance criteria - A fresh reader of root `CLAUDE.md` gets the real recording flow (per-speaker WAV tracks, `/audio` endpoint, Celery pipeline) with no "not yet implemented" marker. - No doc claims a DML-only app user as a present-tense fact until it is true; wording references the enforcement issue/runbook. - `webapp/CLAUDE.md` stack table matches `package.json` majors; no reference to `init.sql` remains. - `Dockerfile` header comments match the actual base image version. ## References - Root `CLAUDE.md` ("Recording architecture", "Shared infrastructure", repo-structure Python claims) - `webapp/CLAUDE.md:20` (stack table); `webapp/frontend/package.json:15/:18/:27/:30/:31` - `webapp/backend/app/routers/bot.py:657-707` (shipped audio endpoint), `bot/questboard_bot/cogs/recording.py:523-595` (per-speaker pipeline) - `Dockerfile:14/:16/:97/:99` - Related: "[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql" (this milestone) _Filed from the July 2026 full-project review._

claude-bot added the

enhancement

label

2026-07-14 19:51:13 +00:00

claude-bot added this to the v3.3.0 - Hardening: Bugs & Security milestone

2026-07-14 19:51:14 +00:00

claude-bot commented

2026-07-14 19:59:25 +00:00

Author

Collaborator

The Python version-alignment work referenced in item (d) is now filed as #87 (v3.4.0). Align the Dockerfile header comments with whatever #87 decides.

claude-bot referenced this issue

2026-07-14 20:26:48 +00:00

[Hardening] Proxy /public/ so the public analytics share page works #92

claude-bot referenced this issue

2026-07-14 20:26:52 +00:00

[Hardening] Enforce DML-only privileges for the app DB user; remove orphaned init.sql #102

claude-bot commented

2026-07-14 20:26:55 +00:00

Author

Collaborator

Picking this up as part of a v3.3.0 push. Landing on branch hardening/infra-docs together with #92 and #102, so the DB-role wording in item (b) can be written against what #102 actually enforces rather than left aspirational. Item (d) will set the Dockerfile header comments to the real base image (3.14) and reference #87 as the pending alignment decision, per the note above.

Picking this up as part of a v3.3.0 push. Landing on branch `hardening/infra-docs` together with #92 and #102, so the DB-role wording in item (b) can be written against what #102 actually enforces rather than left aspirational. Item (d) will set the Dockerfile header comments to the real base image (3.14) and reference #87 as the pending alignment decision, per the note above.

claude-bot commented

2026-07-14 21:34:37 +00:00

Author

Collaborator

Fixed on main (commits a9a35f7 + c59cdf2, merged via 9448593).

(a) Recording architecture — root CLAUDE.md rewritten from the code (recording.py + process_audio) to describe the shipped flow: per-speaker 16 kHz WAVs + speakers.json → POST /api/bot/sessions/{id}/audio → Celery process_audio transcribes per speaker, merges an attributed transcript, summarises, notifies the bot. "Not yet implemented" block and mono-MP3 wording removed. Also corrected the old "deletes the MP3" step — the per-session dir is kept until GM approval (this is the same lifecycle fact that reshaped #85).
(b) DB roles — root and webapp/CLAUDE.md now describe the three-role split as actually enforced by init.sh per #102, pointing existing installs at the OPERATIONS.md runbook; init.sql reference removed.
(c) Stack versions — webapp/CLAUDE.md table updated to the real package.json versions (React 19, Vite 8, Tailwind 4, react-router-dom 7).
(d) Python version — Dockerfile header comments and root CLAUDE.md set to the real base image (3.14) with a pointer to #87 for the pending 3.12-vs-3.14 alignment decision. No base image or CI version changed (that's #87's job).

Fixed on `main` (commits `a9a35f7` + `c59cdf2`, merged via `9448593`). - **(a) Recording architecture** — root `CLAUDE.md` rewritten from the code (`recording.py` + `process_audio`) to describe the shipped flow: per-speaker 16 kHz WAVs + `speakers.json` → `POST /api/bot/sessions/{id}/audio` → Celery `process_audio` transcribes per speaker, merges an attributed transcript, summarises, notifies the bot. "Not yet implemented" block and mono-MP3 wording removed. Also corrected the old "deletes the MP3" step — the per-session dir is kept until GM approval (this is the same lifecycle fact that reshaped #85). - **(b) DB roles** — root and `webapp/CLAUDE.md` now describe the three-role split as actually enforced by `init.sh` per #102, pointing existing installs at the OPERATIONS.md runbook; `init.sql` reference removed. - **(c) Stack versions** — `webapp/CLAUDE.md` table updated to the real `package.json` versions (React 19, Vite 8, Tailwind 4, react-router-dom 7). - **(d) Python version** — `Dockerfile` header comments and root `CLAUDE.md` set to the real base image (3.14) with a pointer to #87 for the pending 3.12-vs-3.14 alignment decision. No base image or CI version changed (that's #87's job).

claude-bot closed this issue

2026-07-14 21:34:54 +00:00