# Core components

**Audience:** Developers

## Core components

This page is the single reference for GL Open DeepResearch **core components** and their roles. For how they are layered and how request/task flow works, see [Architecture diagram](https://gdplabs.gitbook.io/gl-open-deepresearch/developers-guide/introduction/architecture-diagram). For pipelines and design patterns, see [Core design principles](https://gdplabs.gitbook.io/gl-open-deepresearch/developers-guide/introduction/design-principles).

### API and request handling

| Component          | Role                                                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Router**         | HTTP request/response handling: task and taskgroup creation/retrieval, task and taskgroup streaming, profiles, accounts, health. Validates input and delegates to services. |
| **Authentication** | API key verification (`X-API-Key`). Master key for admin routes; account key for scoped access.                                                                             |

### Orchestration and execution

| Component                 | Role                                                                                                                                                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Orchestrator Factory**  | Builds the request-scoped runtime: resolves profile (Profile Registry), creates adapter (Orchestrator Registry), optional tools (Tool Registry), then instantiates the orchestrator. One orchestrator per research run. |
| **Orchestrator**          | Holds adapter, profile, and optional tools; invokes the adapter’s `run()` with the query and optional event emitter. Same path when run inside the worker (streaming, task, taskgroup).                                 |
| **Orchestrator Adapter**  | Protocol (name, provider type, description, streaming postprocessor, `run`). Implementations: TongyiAdapter, GPTResearcherAdapter. Execute the underlying research engine and return standardized results.              |
| **Profile Registry**      | Resolves profiles by name; caches and stays consistent with the database (create/update/delete via ProfileService). Used by Orchestrator Factory.                                                                       |
| **Orchestrator Registry** | Adapter factories keyed by provider name (e.g. tongyi, gptr). Creates one adapter instance per request. Populated at startup.                                                                                           |
| **Tool Registry**         | Tool factories by name (e.g. web\_search, fetch\_web\_page). Used by Orchestrator Factory when the profile specifies tools.                                                                                             |
| **Config Resolver**       | Loads runtime config from environment and database; validates profile/provider and default profile.                                                                                                                     |

### Tasks and streaming

| Component              | Role                                                                                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Task Service**       | Creates tasks, updates status, retrieves task/status/result, runs research execution in the worker, provides task stream. Persists tasks and enqueues work to Celery.                                 |
| **TaskGroup Service**  | Creates taskgroups (shared profile/webhook), creates member tasks via Task Service, derives group status from task statuses, provides group stream (aggregated task + taskgroup streams).             |
| **Job queue**          | Celery broker; decouples API from execution.                                                                                                                                                          |
| **Worker**             | Celery workers consume tasks, build orchestrator via Factory, run adapter, capture events to Redis, update status, trigger webhooks.                                                                  |
| **Event stream**       | Capture adapter events during execution → append to Redis lists (task\_stream, taskgroup\_stream) with TTL → clients consume via SSE. One generic Redis-stream reader for task and taskgroup streams. |
| **Webhook Dispatcher** | Sends webhook on task or taskgroup completion. Optional HMAC; configurable timeout and retries.                                                                                                       |

### Data and infrastructure

| Component    | Role                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **Models**   | Domain models and schemas for research and tasks.                                              |
| **Accounts** | Account management and API key generation/storage (e.g. bcrypt). Repository-based data access. |
| **Redis**    | Streaming event storage (lists with TTL); used by event stream for capture and retrieval.      |

***

Provider-specific behavior (Tongyi, GPT-Researcher) lives in the **adapters** and their underlying engines. See [Available Open Source Deep Research](https://gdplabs.gitbook.io/gl-open-deepresearch/developers-guide/customization/available-deep-research-providers) and the linked provider docs.
