Skip to content

chore: stabilize, document, and rebrand before the frontend phase (9.5) - #15

Merged
withrvr merged 13 commits into
masterfrom
phase-9.5-stabilize-and-rebrand
Sep 13, 2026
Merged

chore: stabilize, document, and rebrand before the frontend phase (9.5)#15
withrvr merged 13 commits into
masterfrom
phase-9.5-stabilize-and-rebrand

Conversation

@withrvr

@withrvr withrvr commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Summary

A deliberate pause between backend work and Phase 10 (frontend): stabilize, document, and rebrand everything built so far. No new game features.

  • Dependency audit (docs/development/dependency-audit.md): 30 backend packages upgraded within existing ranges (uv lock --upgrade), ~20 frontend packages within range (bun update). Two major bumps deliberately deferred to Phase 10 (@tanstack/react-table v8→v9, typescript v6→v7 — both need real code migration in files Phase 10 will touch anyway); axios/form-data's exact pins left alone (unknown reason, not worth the risk).
  • Docs reorganized into docs/: docs/architecture/ gets one historical snapshot per completed phase (00–9, plus 2b for the template pivot) plus an always-current latest_architecture.md; docs/api/api-reference.md generated from the real route/model code; docs/stack.md, docs/development/setup.md, docs/deployment/{staging,production}.md consolidated from scattered/stray root docs (all deleted). DECISIONS.md/PROGRESS.md stay at root as the project's permanent logs.
  • scripts/dev.sh: one-command tmux dev launcher (backend, frontend, Compose, logs), idempotent, actually run twice to verify.
  • Rebranding: every trace of the template's cosmetic identity removed — package names, frontend title/favicon/logo/footer, template screenshot assets. DECISIONS.md/PROGRESS.md/.github/workflows/* deliberately untouched (legitimate history / a standing, recorded Phase-14 deferral).
  • Root files: README.md rewritten marketing-facing, CONTRIBUTING.md rewritten with real conventions, added LICENSE (MIT), CODE_OF_CONDUCT.md (Contributor Covenant), SECURITY.md, llms.txt.
  • Two real regressions caught and fixed by re-running the full gate after every merge: renaming backend/pyproject.toml's package broke hatchling's wheel file-selection (fixed with explicit packages = ["app"]); renaming frontend/package.json's package broke every bun run --filter frontend ... call site this repo's own tooling depends on (fixed in root package.json and scripts/generate-client.sh; .github/workflows/deploy.yml's identical stale reference left alone per the Phase 14 deferral).
  • Not done, per the brief's own instruction to say so rather than add unused placeholders: robots.txt/sitemap.xml/OG tags — they only make sense once a deployed, crawlable frontend exists, and neither does yet.

Process note

Used git worktrees + parallel subagents for the three genuinely independent pieces (docs reorg, scripts/dev.sh, rebrand+root-files), per the brief. Planned directly rather than through a separate planner-agent call — full context of all nine prior phases was already in hand from having built them this session, so a fresh planner subagent would only re-derive it from this same PROGRESS.md at real cost, not add judgment.

Verification

  • Backend: ruff check/mypy app/ty check app clean, full suite 753 tests green.
  • Frontend: bun run build/bun run lint clean.
  • prek run --all-files clean across the whole repo.
  • Every markdown file lives under docs/ except README.md and the standard root files (LICENSE, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md) plus DECISIONS.md/PROGRESS.md (permanent project logs, not "documentation to reorganize").

https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8

@withrvr
feat(dev): add tmux-based one-command dev environment script
73ff2aa 
Adds scripts/dev.sh: starts backend (uv run fastapi dev), frontend
(bun run dev, guarded to skip cleanly if package.json ever lacks a dev
script), Postgres/Redis via docker compose (idempotent up, skips if
already running), and a window tailing compose logs for db/redis (the
backend has no LOG_FILE by default, so its own reload window already
shows its stdout logs live). All windows live in one botpit-dev tmux
session; re-running the script attaches to the existing session instead
of duplicating it.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
merge: task/phase-9.5/dev-script
60ac7f5
@withrvr
chore(deps): audit and upgrade to latest stable dependencies (Phase 9.5)
826007a 
Backend (uv lock --upgrade): 30 packages bumped within their existing
pyproject.toml ranges (fastapi, sqlalchemy, sqlmodel, starlette, uvicorn,
pydantic, alembic, psycopg, etc.) -- full suite (753 tests) and
ruff/mypy/ty all green after.

Frontend (bun update): within-range bumps to react-query/router, react,
react-hook-form, lucide-react, tailwindcss, biome, vite, and others --
build and lint clean after (aside from pre-existing template-logo lint
findings a parallel rebranding task resolves).

Deliberately not bumped (documented in docs/development/dependency-audit.md
once that file lands): @tanstack/react-table (v8->v9, a major bump needing
real code migration in DataTable.tsx/columns.tsx -- deferred to Phase 10,
which will likely touch those files anyway) and typescript (v6->v7, same
reasoning); axios/form-data (exact-pinned, not caret -- left untouched
rather than overriding what looks like a deliberate pin without knowing
why).

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
docs: reorganize documentation into docs/ (Phase 9.5)
065e108 
Moves every botpit-relevant doc under docs/ per the target structure:
- docs/architecture/phase-{01..09,02b}-*.md: one historical snapshot per
  completed phase, mined from PROGRESS.md's own build log plus the actual
  code/tests from each phase; docs/architecture/latest_architecture.md is
  a fresh, current-state snapshot read directly from backend/app/.
- docs/api/api-reference.md: generated from the actual routes, Pydantic
  models, and event schema in backend/app/, including the event
  visibility/filtering rules.
- docs/development/setup.md and docs/deployment/{staging,production}.md:
  botpit-specific rewrites folding in the real operational content from
  the template's own root deployment.md/deployment-docker-compose.md/
  development.md (now deleted), stripped of template branding. Staging
  and production are documented as planned, not live, per the standing
  no-server-until-local-is-done constraint.
- docs/stack.md: consolidates docs/research/stack-choices.md (now
  deleted, along with the empty research/ dir) with DECISIONS.md's
  reasoning into one technology-surface reference.
- docs/persistence.md rewritten: it still described Phase 1's async
  SQLAlchemy/SQLite-dual-dialect design, superseded at Phase 2b by the
  template's sync SQLModel/Postgres-only persistence layer.
- release-notes.md (the upstream template's own changelog) deleted.

Every other pre-existing docs/*.md file was reviewed and left in place —
none were stubs.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
fix(branding): remove template branding and add standard root files
30aa38a 
Renames backend/pyproject.toml and frontend/package.json off their
template-inherited "app"/"frontend" placeholder names; replaces the
Full-Stack-FastAPI-Project title/favicon/logo/footer credits across
frontend/index.html and frontend/src/ with a plain botpit wordmark and a
link to the real repo; deletes the now-unreferenced template logo/favicon
SVGs.

Rewrites README.md (marketing-facing, links out to docs/ instead of
inlining technical detail) and CONTRIBUTING.md (real branch/PR
conventions and gate commands, not the template's). Adds LICENSE (MIT),
CODE_OF_CONDUCT.md (Contributor Covenant v2.1), SECURITY.md (private
GitHub advisory reporting, given real auth/RBAC now exists), and llms.txt
(a factual project summary for crawlers/LLM tools).

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
merge: task/phase-9.5/rebrand-and-root-files
381793d
@withrvr
merge: task/phase-9.5/docs-reorg
c0731f7
@withrvr
fix: package-rename regressions from the rebrand, plus the dependency…
0bfa7b8 
… audit doc

Renaming backend/pyproject.toml's project name off "app" broke hatchling's
default wheel file-selection heuristic (it looks for a source directory
matching the project name; the actual tree is still app/) -- fixed with an
explicit [tool.hatch.build.targets.wheel] packages = ["app"].

Renaming frontend/package.json's name off "frontend" broke every
`bun run --filter frontend ...` call site outside .github/workflows/ (root
package.json's dev/lint/test scripts, scripts/generate-client.sh) --
updated to --filter botpit-frontend. .github/workflows/deploy.yml has the
same stale reference but stays untouched, matching the standing decision
(PROGRESS.md, Phase 2b) to leave template CI/deploy workflows as-is until
Phase 14.

Also adds docs/development/dependency-audit.md, recording the Phase 9.5
dependency-upgrade pass already committed on this branch.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
docs: Phase 9.5 progress record, delete unreferenced template screens…
afe766b 
…hots

PROGRESS.md: fix stale "PR pending" text on Phases 6-9's status rows (all
merged, PR numbers known) and record Phase 9.5 in full.

img/: nine full-stack-fastapi-template dashboard/login/mailpit screenshots,
unreferenced by the rewritten README -- the last piece of carried-over
template branding this phase's other tasks didn't have in their explicit
scope.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
docs: fix leave_room status codes in api-reference.md
c7054ce 
service.leave() calls self.get(room_id) first, which raises LookupError
(-> 404) for an unknown room -- the doc said "always 200," missing that
path. Caught by the python-reviewer round on PR #15.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
docs: fix code-review findings on PR #15
19c74ac 
README overclaimed "real time" spectator visibility; it's HTTP polling,
per this repo's own llms.txt and latest_architecture.md. Softened and
linked to the API reference instead.

latest_architecture.md drifted within its own phase: written before the
rebranding commit touched frontend/'s title/favicon/logo/footer, then
never updated to say so. Added one clause noting that touch was cosmetic
only.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
fix: regenerate bun.lock after the frontend package rename
1ee8f11 
The rebranding commit renamed frontend/package.json's name from
"frontend" to "botpit-frontend" but never re-ran `bun install`, so
bun.lock still had the workspace entry keyed "frontend" -- CI's
`bun install --frozen-lockfile` correctly caught the mismatch
("lockfile had changes, but lockfile is frozen") and failed the
pre-commit job. Regenerated via a plain `bun install`; frontend
build/lint verified clean after.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
fix: Dockerfile --package app -> --package botpit-backend
b2e7bc2 
Same class of regression as the earlier hatchling fix: the rebrand
renamed the backend's uv package off "app", but the Dockerfile's two
`uv sync ... --package app` invocations were never updated, breaking
every docker-compose-based CI job (test-docker-compose, all 4
test-playwright shards) with "error: Could not find root package `app`".

Verified locally: docker compose build, prestart.sh, and up --wait
backend adminer all succeed; both CI health-check curls pass against the
running stack.

Claude-Session: https://claude.ai/code/session_01PVbV8Fd3gk6zGDabt8AWP8
@withrvr
withrvr merged commit 69190b2 into master Sep 13, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@withrvr