Reorganize backend by topic (vertical slice) [stacked on #112]

[anth-volk]

Summary

Reorganizes the backend from its mixed structure (HTTP-layer routes/, topic
tooling/+evaluation/, grab-bag package root) into package-by-topic: each
folder is one requirement, each file one sub-responsibility — including that
topic's own route file and config. Pure structural change; runtime behaviour
is identical.

Final tree: api/ · billing/ · chat/ · config/ · conversations/ · engine/ · eval/ · gateway/ · prompts/ · tools/ (+ tests/).

Closes #115. Implements the proposal in #114.

⚠️ Stacked on #112 — do not merge first

This branch is based on feat/chat-gateway (#112) and the PR targets it, not
main. Three packages (config/, gateway/, the gateway-aware chat/ split)
come from files that only exist on #112, and most slices collide with #112's
edits to chatbot.py / prompts.py / evaluation/* / build_reference.py.
Merge after #112, then retarget this PR to main.

How it was done

A 10-step loop — one topic package per commit, leaf → root, each independently
runnable and test-green:

commit	slice
refactor(engine)	tooling/ + build_reference.py → engine/
refactor(config)	model_config.py + chat-only model constants → config/{models,sampling,clients,scope}
refactor(prompts)	prompts.py → prompts/{system,gateway,meta}
refactor(tools)	tool_definitions.py/agent_tools.py → tools/{definitions,dispatch}
refactor(gateway)	gateway.py/gateway_config.py → gateway/{runtime,policy}
refactor(billing)	routes/billing.py → billing/{pricing,credits,stripe,routes}
refactor(conversations)	routes/conversations.py → conversations/{models,schemas,store,sharing,reports,routes}
refactor(chat)	routes/chatbot.py (707 lines) → chat/{orchestrator,system_blocks,model_selection,schemas,titles,suggestions,routes}
refactor(eval)	evaluation/ → eval/
refactor(api)	main.py/rate_limit.py → api/{main,errors,rate_limit}
docs(skills)	update uk-chat-runtime.md + ai-evals.md path maps

Design notes:

• Re-exporting __init__s (config, prompts, gateway, billing, conversations,
  chat) keep most importers unchanged. Tests that reach into module internals
  got precise submodule aliases (chat.orchestrator, gateway.runtime,
  tools.dispatch, conversations.models).
• config/ collapses the DEFAULT_FAST_MODEL-here / DEFAULT_COMPLEX_MODEL-there
  asymmetry — all model-call config now lives in one place; the
  scope_descriptor.md path was fixed (parent → parent.parent).
• chat/orchestrator.py keeps the SSE streaming tool loop verbatim; the mocked
  end-to-end stream + tool-loop test validates it.
• Route paths (/chat/*, /billing/*, /conversations/*), the
  reference.md/scope_descriptor.md output locations, and the
  evals/cases/* resolution are all unchanged.

Verification

• Full backend suite: 155 passed, 10 skipped — at every commit.
• make eval-ai-offline: 95 passed, 0 failed, 41 skipped (baseline unchanged).
• uvicorn api.main:app boots; /health + /version return 200; startup
  ensure_table wired.
• Deploy entrypoints updated (modal_app.py, backend/Dockerfile, Makefile).
• Stale-path sweep clean (no references to any moved module).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
policyengine-uk-chat	Ready	Preview, Comment	Jun 18, 2026 7:41pm

[github-actions]

Beta preview is ready.

• Frontend: open preview
• Backend: open backend

[vahid-ahmadi]

Review — backend reorg to package-by-topic (draft, stacked on #112)

I verified this as what it claims to be: a faithful pure-structural refactor. I checked the low-similarity splits closely (the risky ones), confirmed the re-export shims, and confirmed the deploy wiring. Findings below.

Faithfulness — verified ✅

• The big split routes/chatbot.py (707 lines) → chat/{orchestrator,routes,schemas,suggestions,system_blocks,titles,model_selection}: every function/route present once with identical bodies; constants unchanged (MAX_ITERATIONS=30, max_tokens 16000/200/32, MAX_RESULT_CHARS, max_retries=2); inline model/sampling constants moved to config/* with identical values. SSE tool loop kept verbatim.
• prompts.py → prompts/{system,gateway,meta}: every triple-quoted prompt literal is byte-identical (no wording/whitespace drift), same SYSTEM_PROMPT_SECTIONS ordering and join.
• routes/billing.py → billing/*: all pricing constants, Stripe params, webhook signature handling, and 4 routes preserved.
• main.py → api/{main,errors} and routes/conversations.py → conversations/*: app config, CORS, routers, startup hook, the chat_conversations DB model (column-for-column), and ensure_table() all preserved.
• Re-export __init__ shims (prompts, gateway, config, billing, conversations, chat) re-export the public names external importers actually use, so from prompts import … / from gateway import run_gateway etc. still resolve to the same objects.
• Entrypoints updated consistently: Dockerfile (uvicorn api.main:app, python engine/reference.py), modal_app.py (from api.main import app, build step), Makefile (python -m eval.run). No stale evaluation./scripts//main:app references left.
• Test coverage preserved: I counted def test_ across all six touched test files — identical base vs head (no tests dropped or merged). The 162 → 155 passed delta between this and #112's description is measurement context, not lost coverage; worth a one-line "CI green" confirmation when you de-draft.

The one buried behavioural change — fine, but mildly mis-described

The PR calls the parent → parent.parent edit in the scope-descriptor path a "fix". It's actually compensation: load_scope_descriptor moved from backend/model_config.py to backend/config/scope.py (one directory deeper), so it needs an extra .parent to resolve to the same backend/scope_descriptor.md. Net runtime target is unchanged — correct, but "fix" overstates it; it'd be clearer to describe it as path-compensation for the move so a future reader doesn't go hunting for the bug it "fixed".

Other small undocumented deltas (benign)

• api/main.py swaps @app.exception_handler(RateLimitExceeded) for app.add_exception_handler(RateLimitExceeded, rate_limit_handler) — equivalent in Starlette, but it's a behavioural-looking change inside a "pure move" PR; worth a word in the commit body.
• conversations/models.py drops an unused timezone import. Harmless.
• New tests/conftest.py (rate-limit env bumps, sqlite isolation, a requires_compiled skip marker) is a good addition and well-commented.

My actual concern: the stacking order

The code is sound; the risk is process. This is a 74-file move stacked on #112, which is uncalibrated and explicitly expects tuning (its own follow-up is "run the live eval and tune the gateway prompt + promotions against misroutes"). Any such tuning — prompt edits, the keyword-promotion fixes I flagged on #112, criticality tweaks — lands in the exact files this PR moves (gateway/*, prompts/*, chat/*), forcing a rebase of all 74 files each time. Refactoring on top of a moving, unmerged target is avoidable churn.

Recommendation, matching the draft status:

1. Land #112 and let it stabilise through its live calibration.
2. Then do this reorg against main (retarget as the description says).

Keeping it a draft until #112 merges is exactly right. Once it's rebased onto a settled #112, this is a clean, well-sequenced refactor (one topic package per commit, test-green at each) and I'd be happy to approve it. Nice work on the leaf→root commit discipline.