# Class diagram

**Audience:** Developers

{% @mermaid/diagram content="classDiagram
%% Enums
class ProviderType {
<<enumeration>>
INTERNAL
GPTR
}

```
class DeepResearchStatus {
    <<enumeration>>
    PENDING
    RECEIVED
    STARTED
    SUCCESS
    FAILURE
    REVOKED
    RETRY
}

%% Domain Models
class DeepResearchResult {
    +query
    +result
    +profile
    +duration
    +created_at
    +completed_at
}

class Profile {
    +name
    +provider
    +params
    +description
    +updated_at
}

%% Base Adapter Protocol
class OrchestratorAdapter {
    <<Protocol>>
    +name
    +provider_type
    +description
    +run()
}

class ProviderError {
    +message
    +provider_type
    +original_error
}

%% Factory
class OrchestratorFactory {
    -_profile_service
    +create()
    +list_available_providers()
    -_create_adapter()
    -_load_profile()
}

%% Orchestrator
class DeepResearchOrchestrator {
    -_adapter
    -_profile
    +conduct_research()
}

%% Adapter Implementations
class TongyiAdapter {
    +name
    +provider_type
    +description
    +run()
    -_check_env_variables()
    -_build_llm_config()
    -_initialize_agent()
}

class GPTResearcherAdapter {
    +name
    +provider_type
    +description
    +run()
}

%% Profile Management - Service Layer
class ProfileService {
    -_repository
    +get_all_profiles()
    +get_profile_by_name()
    +get_profile()
    +create_profile()
    +update_profile()
    +delete_profile()
    +get_default_profile()
}

%% Profile Management - Repository Layer
class BaseRepository {
    <<abstract>>
    +get_all()
    +get_by_name()
    +get_default_profile()
    +create()
    +update()
    +delete()
}

class SqlAlchemyProfileRepository {
    -db
    +get_all()
    +get_by_name()
    +get_default_profile()
    +create()
    +update()
    +delete()
}

class ProfileModel {
    +name
    +provider
    +params
    +description
    +updated_at
}

%% Configuration
class Settings {
    +app_name
    +app_version
    +description
    +debug
    +log_level
    +default_provider
    +default_profile
    +db_url
}

%% Request/Response Schemas
class DeepResearchRequest {
    +query
    +profile
    +as_form()
}

class DeepResearchResponse {
    +status
    +data
    +error
}

%% Accounts API
class AccountsRouter {
    +create_account()
    +list_accounts()
    +get_account()
    +delete_account()
}

class AccountService {
    +create_account()
    +list_accounts()
    +get_account()
    +delete_account()
}

class BaseAccountRepository {
    <<abstract>>
    +create()
    +get_by_id()
    +get_by_name()
    +get_all()
    +delete()
}

class SqlAlchemyAccountRepository {
    +create()
    +get_by_id()
    +get_by_name()
    +get_all()
    +delete()
}

class Account {
    +id
    +name
    +hashed_api_key
    +key_preview
    +created_at
    +updated_at
    +deleted_at
}

class AccountModel {
    +id
    +name
    +hashed_api_key
    +key_preview
    +created_at
    +updated_at
    +deleted_at
}

%% Authentication
class ApiKeyAuth {
    +verify_api_key()
    +verify_master_api_key()
    +get_master_api_key()
}

%% Tasks API
class TasksRouter {
    +create_task()
    +get_task()
    +get_task_status()
}

class TaskService {
    +create_task()
    +get_task()
    +get_task_status()
}

class BaseTaskRepository {
    <<abstract>>
    +create()
    +get_by_id()
    +update()
}

class SqlAlchemyTaskRepository {
    +create()
    +get_by_id()
    +update()
}

class Task {
    +id
    +status
    +query
    +profile
    +result
    +webhook_url
    +webhook_secret
    +created_at
    +updated_at
    +account_id
}

class TaskModel {
    +id
    +status
    +query
    +profile
    +result
    +webhook_url
    +webhook_secret
    +created_at
    +updated_at
    +account_id
}

class conduct_research_task {
    <<CeleryTask>>
    +run()
}

class Redis {
    <<Infrastructure>>
}

%% Task Groups API
class TaskGroupsRouter {
    +create_task_group()
    +get_task_group()
    +add_task_to_group()
    +get_task_in_group()
    +get_group_stream()
    +get_task_stream_in_group()
}

class TaskGroupService {
    +create_task_group()
    +get_task_group()
    +add_task_to_group()
    +get_task_in_group()
    +get_group_stream()
    +get_task_stream_in_group()
    +validate_task_group_exists()
    +validate_task_in_group()
}

class BaseTaskGroupRepository {
    <<abstract>>
    +create()
    +get_by_id()
    +update()
    +get_tasks_by_group()
}

class SqlAlchemyTaskGroupRepository {
    +create()
    +get_by_id()
    +update()
    +get_tasks_by_group()
}

class TaskGroup {
    +taskgroup_id
    +status
    +profile
    +webhook_url
    +webhook_secret
    +created_at
    +updated_at
}

class TaskGroupModel {
    +taskgroup_id
    +status
    +profile
    +webhook_url
    +webhook_secret
    +created_at
    +updated_at
}

class RedisCacheManager {
    +append_to_list()
    +get_list()
    +get_list_length()
    +clear()
}

class TaskStreamingHandler {
    +setup_streaming_handlers()
    +store_completion_event()
    +cleanup_streaming_handlers()
}

%% Relationships
DeepResearchResult --> Profile
Profile --> ProviderType

OrchestratorAdapter <|.. TongyiAdapter : implements
OrchestratorAdapter <|.. GPTResearcherAdapter : implements

OrchestratorFactory --> ProfileService
OrchestratorFactory --> OrchestratorAdapter
OrchestratorFactory --> DeepResearchOrchestrator

DeepResearchOrchestrator --> OrchestratorAdapter
DeepResearchOrchestrator --> Profile
DeepResearchOrchestrator --> DeepResearchRequest
DeepResearchOrchestrator --> DeepResearchResult

TongyiAdapter --> Profile
GPTResearcherAdapter --> Profile

ProfileService --> BaseRepository
BaseRepository <|-- SqlAlchemyProfileRepository
SqlAlchemyProfileRepository --> ProfileModel
ProfileModel ..> Profile : maps to

Settings --> ProviderType

ProviderError --> ProviderType

%% Accounts API Relationships
AccountsRouter --> AccountService
AccountsRouter --> ApiKeyAuth
AccountService --> BaseAccountRepository
BaseAccountRepository <|-- SqlAlchemyAccountRepository
SqlAlchemyAccountRepository --> AccountModel
AccountModel ..> Account : maps to
ApiKeyAuth --> AccountService

%% Tasks API Relationships
TasksRouter --> TaskService
TasksRouter --> ApiKeyAuth
TaskService --> ProfileService
TaskService --> BaseTaskRepository
BaseTaskRepository <|-- SqlAlchemyTaskRepository
SqlAlchemyTaskRepository --> TaskModel
TaskModel ..> Task : maps to
TaskService --> conduct_research_task
TaskService --> RedisCacheManager
conduct_research_task --> OrchestratorFactory
conduct_research_task --> DeepResearchOrchestrator
conduct_research_task --> DeepResearchResult
conduct_research_task --> TaskStreamingHandler
TaskStreamingHandler --> RedisCacheManager
conduct_research_task ..> Redis

%% Task Groups API Relationships
TaskGroupsRouter --> TaskGroupService
TaskGroupsRouter --> ApiKeyAuth
TaskGroupService --> TaskService
TaskGroupService --> BaseTaskGroupRepository
BaseTaskGroupRepository <|-- SqlAlchemyTaskGroupRepository
SqlAlchemyTaskGroupRepository --> TaskGroupModel
TaskGroupModel ..> TaskGroup : maps to
TaskGroupService --> RedisCacheManager
TaskGroupService --> TaskStreamingHandler
Task --> TaskGroup
RedisCacheManager ..> Redis" %}
```