Architecture
System responsibilities, request flow, and implementation boundaries.
System Components
- FastAPI routers: request validation, response typing, route orchestration.
- Services layer: external API clients and composition logic.
- Reranker: merges Tavily results with Cohere relevance ordering.
- Context builder: conversation-history-aware query construction.
- Store: in-memory conversation repository.
Responsibility Split
Routers -> Services -> External Providers- Routers should stay thin.
- Provider-specific behavior is isolated in service modules.
- Shared flow logic (
search_flow) is reused across/search,/answer, and conversation message handling.
Request Lifecycles
/search
- Validate query parameters.
- Retrieve from Tavily.
- Attempt Cohere rerank.
- Fallback to native Tavily ordering on rerank failure.
- Return typed response.
/answer
- Execute search flow.
- Select top sources.
- Build synthesis prompt.
- Generate answer with citations.
/conversations/{id}/messages
- Validate conversation + query.
- Build context-enriched retrieval query.
- Execute search flow.
- Synthesize response with history context.
- Persist message result.
Reliability and Failure Strategy
- Provider failures return structured 5xx with stable error codes.
- Non-critical rerank failures degrade gracefully.
- Global exception handling normalizes unhandled failures.