Summary
\�pp/src/thread_observability/api/http_api.py\ has become a broad application shell rather than a focused API entrypoint. It currently mixes route definitions, diagnostics shaping, chat telemetry, conversation extraction, and app lifespan orchestration in one file.
This issue is to decompose the module so HTTP route wiring, diagnostics shaping, and chat-related helpers are easier to reason about and test independently.
Evidence from review
The review found all of the following concentrated in one module:
- diagnostics summary building
- chat telemetry recording
- chat turn extraction / response shaping
- background periodic/lifespan orchestration
- a large number of route handlers spanning unrelated domains
The file is large not just because there are many endpoints, but because it also owns helper logic that should not have to live in the main application factory.
Scope
Refactor the module into clearer pieces, for example:
- route modules by domain or feature
- extracted diagnostics payload builder(s)
- extracted chat HTTP helper/service layer
- a thinner core app factory / lifespan surface
Exact file names are flexible. The key outcome is reduced cross-cutting responsibility inside \http_api.py.
Guardrails
- Preserve route paths and response contracts unless a behavior change is explicitly intended elsewhere.
- Do not conflate this with frontend changes.
- Avoid changing business logic unless the existing structure makes a bug obvious and tests cover the change.
Acceptance Criteria
- \http_api.py\ is materially smaller and more focused.
- Diagnostics shaping no longer has to live inside the main route file.
- Chat HTTP handling is easier to follow and test.
- Lifespan / background orchestration is clearer and isolated.
- Existing API and contract tests still pass.
Notes
This should make future API additions safer and reduce the chance of unrelated merge conflicts.
Summary
\�pp/src/thread_observability/api/http_api.py\ has become a broad application shell rather than a focused API entrypoint. It currently mixes route definitions, diagnostics shaping, chat telemetry, conversation extraction, and app lifespan orchestration in one file.
This issue is to decompose the module so HTTP route wiring, diagnostics shaping, and chat-related helpers are easier to reason about and test independently.
Evidence from review
The review found all of the following concentrated in one module:
The file is large not just because there are many endpoints, but because it also owns helper logic that should not have to live in the main application factory.
Scope
Refactor the module into clearer pieces, for example:
Exact file names are flexible. The key outcome is reduced cross-cutting responsibility inside \http_api.py.
Guardrails
Acceptance Criteria
Notes
This should make future API additions safer and reduce the chance of unrelated merge conflicts.