dravr-platform: routes/chat.rs refactor plan (1290 → 5-6 submodules)

chat_refactor_plan.md

routes/chat.rs refactor plan

Current state (2026-04-21, main @ 51002216)

File	Lines	Verdict
crates/pierre-server/src/routes/chat.rs	1290	too big — refactor
crates/pierre-server/src/services/chat_pipeline/mod.rs	945	big but cohesive; small extraction worth doing
crates/pierre-database/src/database/chat.rs	643	borderline; one concern (chat DB) so OK
crates/pierre-database/src/plugins/postgres/chat.rs	506	same as above
chat_pipeline/{channel_profile,hooks,turn}.rs	≤193	already well-sized

Max function length inside routes/chat.rs:

Method	Lines
send_message	168
send_insight_message	147
run (AgUi)	98
check_pre_chat_quotas	79
create_conversation	61

CLAUDE.md guideline is max 50 lines per function. Top 3 blow past it.

Concerns inside routes/chat.rs

One impl ChatRoutes block holds 20 methods covering 5 distinct concerns:

1. Conversation CRUD — create_conversation, list_conversations, get_conversation, update_conversation, delete_conversation, get_messages (~200 lines)
2. Web chat send — send_message + its post-pipeline helpers (~180 lines)
3. Insight send — send_insight_message + parse_insight_json_response + InsightGenerationResponse (~200 lines)
4. Quotas — check_pre_chat_quotas, select_usage_warning, apply_usage_warning_headers (~110 lines)
5. LLM usage bookkeeping — record_llm_usage, increment_usage_counters, extract_or_estimate_tokens, post_process_content, tokens_from_dispatch, RecordLlmUsageParams (~130 lines)

Plus routing glue (routes(), authenticate, get_tenant_id, get_llm_provider, setup_agui, AgUiWiring) and request/response DTOs.

Target layout

routes/chat.rs                    <- router wiring + shared DTOs + small auth/provider helpers
routes/chat/conversations.rs      <- CRUD (create/list/get/update/delete/get_messages)
routes/chat/send_message.rs       <- send_message + its inline post-processing
routes/chat/send_insight.rs       <- send_insight_message + parse_insight_json_response
routes/chat/quotas.rs             <- check_pre_chat_quotas + warning helpers
routes/chat/usage.rs              <- record_llm_usage + token estimation + post-process

Rules:

• Every new file has the ABOUTME: ... banner per CLAUDE.md.
• No new traits or abstractions introduced — we're moving code, not designing new types.
• Shared DTOs stay in routes/chat.rs (or move to a dto sibling if there are many).
• pub(super) or pub(crate) on helpers that used to be fn inside impl ChatRoutes — no API change for external callers.
• Each extracted module owns its own use list so top-level routes/chat.rs imports shrink.
• Long methods (send_message, send_insight_message) get split into 3–4 named helpers inside their new file so they each drop below the 50-line guideline.

chat_pipeline/mod.rs follow-up (same PR)

Two helpers inside mod.rs can move to stages/:

Helper	Lines	New home
dispatch_llm_with_tools	119	stages/tool_dispatch.rs
assemble_prompt_and_messages	131	merged into stages/prompt_builder.rs (already exists)

Drops mod.rs from 945 → ~700 lines and concentrates tool-loop glue with its siblings.

Out of scope (left alone)

• DB files (database/chat.rs, plugins/postgres/chat.rs) — monolithic per-table, splitting by concern inside a single-table repo trades small files for cross-file hopping without clarifying anything.
• chat_pipeline/{channel_profile,hooks,turn}.rs — already well-sized.
• services/chat_orchestration.rs (50), services/chat_verdicts.rs (170), services/chat_provider_factory.rs (57), routes/chat_tool_loop.rs (12) — small and focused.

Validation plan

• ./scripts/ci/pre-push-validate.sh must be green.
• Full workspace clippy (cargo clippy --all-targets --all-features -- -D warnings) clean.
• Full-suite CI green on the feature branch before squash merge.
• No behavioral changes expected — pure code reorg.