# eudalabs/ddgs architecture

> Architecture diagram of the GitHub repository eudalabs/ddgs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eudalabs/ddgs
- Repository: https://github.com/eudalabs/ddgs
- Video tour (about a minute): https://gitdiagram.com/eudalabs/ddgs/video

## Overview

DDGS is a Node.js wrapper that uses a browser to retrieve DuckDuckGo web, image, video, and news search results. A consumer calls the exported service facade, which delegates each search to a dedicated service; the service validates the query, configures a browser page, navigates to DuckDuckGo, and extracts results. Shared browser setup and error handling support these flows. The news service is included based on the README and source tree; its implementation was not sampled, so its internal wiring is not expanded.

Main entry points: [`src/services/index.ts`](https://github.com/eudalabs/ddgs/blob/main/src/services/index.ts) (Service Facade), [`src/services/search.ts`](https://github.com/eudalabs/ddgs/blob/main/src/services/search.ts) (Web Search), [`src/services/images.ts`](https://github.com/eudalabs/ddgs/blob/main/src/services/images.ts) (Image Search), [`src/services/videos.ts`](https://github.com/eudalabs/ddgs/blob/main/src/services/videos.ts) (Video Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_entry["Package Exports<br/>[index.ts]"]
  node_facade["Service Facade<br/>[index.ts]"]
end

subgraph group_search["Search Services"]
  node_web["Web Search<br/>[search.ts]"]
  node_images["Image Search<br/>[images.ts]"]
  node_videos["Video Search<br/>[videos.ts]"]
  node_news["News Search<br/>[news.ts]"]
end

subgraph group_runtime["Shared Runtime"]
  node_selectors["Page Selectors<br/>[selectors.ts]"]
  node_base["Browser Support<br/>[base.ts]"]
  node_errors["Error Handling<br/>[errors.ts]"]
end

node_consumer(("Library Consumer"))
node_duckduckgo(("DuckDuckGo"))

node_consumer -->|"imports"| node_entry
node_entry -->|"exports"| node_facade
node_consumer -->|"calls API"| node_facade
node_facade -->|"delegates search"| node_web
node_facade -->|"delegates images"| node_images
node_facade -->|"delegates videos"| node_videos
node_facade -->|"delegates news"| node_news
node_web -->|"uses browser support"| node_base
node_images -->|"uses browser support"| node_base
node_videos -->|"uses browser support"| node_base
node_web -->|"reads selectors"| node_selectors
node_images -->|"reads selectors"| node_selectors
node_videos -->|"reads selectors"| node_selectors
node_web -->|"navigates and reads"| node_duckduckgo
node_images -->|"navigates and reads"| node_duckduckgo
node_videos -->|"navigates and reads"| node_duckduckgo
node_web -->|"raises errors"| node_errors
node_images -->|"raises errors"| node_errors
node_videos -->|"raises errors"| node_errors
node_web -->|"returns results"| node_facade
node_images -->|"returns results"| node_facade
node_videos -->|"returns results"| node_facade
node_news -->|"returns results"| node_facade
node_facade -->|"returns results"| node_consumer

click node_entry "https://github.com/eudalabs/ddgs/blob/main/src/index.ts"
click node_facade "https://github.com/eudalabs/ddgs/blob/main/src/services/index.ts"
click node_web "https://github.com/eudalabs/ddgs/blob/main/src/services/search.ts"
click node_images "https://github.com/eudalabs/ddgs/blob/main/src/services/images.ts"
click node_videos "https://github.com/eudalabs/ddgs/blob/main/src/services/videos.ts"
click node_news "https://github.com/eudalabs/ddgs/blob/main/src/services/news.ts"
click node_selectors "https://github.com/eudalabs/ddgs/blob/main/src/selectors.ts"
click node_base "https://github.com/eudalabs/ddgs/blob/main/src/services/base.ts"
click node_errors "https://github.com/eudalabs/ddgs/blob/main/src/errors.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_facade toneBlue
class node_web,node_images,node_videos,node_news toneAmber
class node_selectors,node_base,node_errors toneMint
class node_consumer,node_duckduckgo toneIndigo
```

## Components

### Public API

- [Package Exports](https://github.com/eudalabs/ddgs/blob/main/src/index.ts): `src/index.ts`
- [Service Facade](https://github.com/eudalabs/ddgs/blob/main/src/services/index.ts): `src/services/index.ts`

### Search Services

- [Web Search](https://github.com/eudalabs/ddgs/blob/main/src/services/search.ts): `src/services/search.ts`
- [Image Search](https://github.com/eudalabs/ddgs/blob/main/src/services/images.ts): `src/services/images.ts`
- [Video Search](https://github.com/eudalabs/ddgs/blob/main/src/services/videos.ts): `src/services/videos.ts`
- [News Search](https://github.com/eudalabs/ddgs/blob/main/src/services/news.ts): `src/services/news.ts`

### Shared Runtime

- [Page Selectors](https://github.com/eudalabs/ddgs/blob/main/src/selectors.ts): `src/selectors.ts`
- [Browser Support](https://github.com/eudalabs/ddgs/blob/main/src/services/base.ts): `src/services/base.ts`
- [Error Handling](https://github.com/eudalabs/ddgs/blob/main/src/errors.ts): `src/errors.ts`

### Other components

- **Library Consumer**
- **DuckDuckGo**

## Connections

- Library Consumer → Package Exports: imports
- Package Exports → Service Facade: exports
- Library Consumer → Service Facade: calls API
- Service Facade → Web Search: delegates search
- Service Facade → Image Search: delegates images
- Service Facade → Video Search: delegates videos
- Service Facade → News Search: delegates news
- Web Search → Browser Support: uses browser support
- Image Search → Browser Support: uses browser support
- Video Search → Browser Support: uses browser support
- Web Search → Page Selectors: reads selectors
- Image Search → Page Selectors: reads selectors
- Video Search → Page Selectors: reads selectors
- Web Search → DuckDuckGo: navigates and reads
- Image Search → DuckDuckGo: navigates and reads
- Video Search → DuckDuckGo: navigates and reads
- Web Search → Error Handling: raises errors
- Image Search → Error Handling: raises errors
- Video Search → Error Handling: raises errors
- Web Search → Service Facade: returns results
- Image Search → Service Facade: returns results
- Video Search → Service Facade: returns results
- News Search → Service Facade: returns results
- Service Facade → Library Consumer: returns results