152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# Research API Separation of Concerns
|
|
|
|
**Date**: 2025-01-29
|
|
**Status**: Completed
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Properly separated Research API types from Blog Writer API to ensure clean separation of concerns. Research components now use dedicated `researchApi.ts` instead of `blogWriterApi.ts`.
|
|
|
|
---
|
|
|
|
## Problem
|
|
|
|
Research components were importing types from `blogWriterApi.ts`, which violated separation of concerns:
|
|
- Research is a standalone engine used by multiple tools (Blog Writer, Podcast Maker, YouTube Creator, etc.)
|
|
- Mixing research types with blog writer types created confusion and tight coupling
|
|
- Made it difficult to maintain and extend research functionality independently
|
|
|
|
---
|
|
|
|
## Solution
|
|
|
|
### Created Dedicated Research API File
|
|
|
|
**`frontend/src/services/researchApi.ts`** - New dedicated file containing:
|
|
- `ResearchMode` - Research depth levels
|
|
- `ResearchProvider` - Provider types (google, exa, tavily)
|
|
- `SourceType` - Source categories
|
|
- `DateRange` - Date filter options
|
|
- `ResearchSource` - Source data structure
|
|
- `ResearchConfig` - Complete research configuration (Exa, Tavily options)
|
|
- `ResearchResponse` - Generic research response interface
|
|
- `ResearchRequest` - Research request interface
|
|
|
|
### Updated All Research Components
|
|
|
|
All Research components now import from `researchApi.ts`:
|
|
|
|
**Updated Files:**
|
|
1. `ExaOptions.tsx` - Uses `ResearchConfig` from `researchApi.ts`
|
|
2. `TavilyOptions.tsx` - Uses `ResearchConfig` from `researchApi.ts`
|
|
3. `ResearchInput.tsx` - Uses `ResearchProvider`, `ResearchMode` from `researchApi.ts`
|
|
4. `AdvancedProviderOptionsSection.tsx` - Uses `ResearchProvider` from `researchApi.ts`
|
|
5. `useResearchWizard.ts` - Uses `ResearchMode`, `ResearchConfig`, `ResearchResponse` from `researchApi.ts`
|
|
6. `research.types.ts` - Uses `ResearchResponse`, `ResearchMode`, `ResearchConfig` from `researchApi.ts`
|
|
7. `StepResults.tsx` - Uses `ResearchResponse` from `researchApi.ts` (casts to `BlogResearchResponse` when needed)
|
|
8. `AdvancedOptionsSection.tsx` - Uses `ResearchConfig` from `researchApi.ts`
|
|
9. `useResearchConfig.ts` - Uses `ResearchProvider` from `researchApi.ts`
|
|
10. `StepOptions.tsx` - Uses `ResearchProvider` from `researchApi.ts`
|
|
11. `researchModeSuggester.ts` - Uses `ResearchMode` from `researchApi.ts`
|
|
|
|
### Backward Compatibility
|
|
|
|
**`frontend/src/services/blogWriterApi.ts`** - Maintains backward compatibility:
|
|
- Re-exports research types from `researchApi.ts` for existing blog writer code
|
|
- `BlogResearchResponse` extends `ResearchResponse` (adds blog-specific fields like `search_widget`, `grounding_metadata`)
|
|
- Blog Writer components continue to work without changes
|
|
|
|
### Adapter Pattern
|
|
|
|
**`BlogWriterAdapter.tsx`** - Uses `BlogResearchResponse`:
|
|
- This is correct - it's an adapter that bridges Research and Blog Writer
|
|
- Adapters are allowed to use both APIs as they translate between domains
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Research Engine │
|
|
│ (Standalone, used by multiple tools) │
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────┐ │
|
|
│ │ researchApi.ts │ │
|
|
│ │ - ResearchConfig │ │
|
|
│ │ - ResearchResponse │ │
|
|
│ │ - ResearchMode, ResearchProvider │ │
|
|
│ └──────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
│
|
|
│ extends
|
|
▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Blog Writer │
|
|
│ (Uses Research Engine) │
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────┐ │
|
|
│ │ blogWriterApi.ts │ │
|
|
│ │ - BlogResearchResponse extends ResearchResponse │ │
|
|
│ │ - Blog-specific fields (search_widget, etc.) │ │
|
|
│ └──────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Benefits
|
|
|
|
1. **Clear Separation**: Research types are separate from Blog Writer types
|
|
2. **Reusability**: Research API can be used by Podcast Maker, YouTube Creator, etc.
|
|
3. **Maintainability**: Changes to research don't affect blog writer and vice versa
|
|
4. **Type Safety**: Proper TypeScript types ensure compile-time safety
|
|
5. **Backward Compatibility**: Existing blog writer code continues to work
|
|
|
|
---
|
|
|
|
## Migration Status
|
|
|
|
✅ **Completed:**
|
|
- Created `researchApi.ts` with all research types
|
|
- Updated all Research components to use `researchApi.ts`
|
|
- Updated `researchEngineApi.ts` to use `ResearchResponse`
|
|
- Maintained backward compatibility in `blogWriterApi.ts`
|
|
- `BlogResearchResponse` properly extends `ResearchResponse`
|
|
|
|
⚠️ **Future Work:**
|
|
- Update blog writer components to import from `researchApi.ts` directly (currently using re-exports)
|
|
- Consider creating adapter components for other tools (Podcast Maker, YouTube Creator)
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
frontend/src/services/
|
|
├── researchApi.ts ← NEW: Dedicated research types
|
|
├── researchEngineApi.ts ← Updated: Uses researchApi.ts
|
|
└── blogWriterApi.ts ← Updated: Re-exports + BlogResearchResponse extends ResearchResponse
|
|
|
|
frontend/src/components/Research/
|
|
├── steps/
|
|
│ ├── components/
|
|
│ │ ├── ExaOptions.tsx ← Uses researchApi.ts
|
|
│ │ ├── TavilyOptions.tsx ← Uses researchApi.ts
|
|
│ │ └── AdvancedOptionsSection.tsx ← Uses researchApi.ts
|
|
│ ├── hooks/
|
|
│ │ └── useResearchConfig.ts ← Uses researchApi.ts
|
|
│ └── utils/
|
|
│ └── researchModeSuggester.ts ← Uses researchApi.ts
|
|
├── types/
|
|
│ └── research.types.ts ← Uses researchApi.ts
|
|
└── integrations/
|
|
└── BlogWriterAdapter.tsx ← Uses blogWriterApi.ts (adapter, correct)
|
|
```
|
|
|
|
---
|
|
|
|
**Status**: ✅ Separation of concerns achieved - Research API is now independent from Blog Writer API
|