AI Analysis and Content Strategy fixes. Enhanced Strategy Routes refactoring.
This commit is contained in:
ajaysi
151
docs/ALwrity Researcher/RESEARCH_API_SEPARATION.md
Normal file
151
docs/ALwrity Researcher/RESEARCH_API_SEPARATION.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user