# https://github.com/degoog-org/degoog Project Manual
Generated at: 2026-07-02 16:01:53 UTC
## Table of Contents
- [Project Overview & Deployment](#page-1)
- [Extension System, Store & Transports](#page-2)
- [Search Backend, Indexer & Data Flow](#page-3)
- [Frontend, Settings UI & Onboarding](#page-4)
## Project Overview & Deployment
### Related Pages
Related topics: [Extension System, Store & Transports](#page-2), [Search Backend, Indexer & Data Flow](#page-3)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
- [docker-compose-examples/simple.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/simple.yml)
- [docker-compose-examples/valkey.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/valkey.yml)
- [docker-compose-examples/postgres.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/postgres.yml)
- [docker-compose-examples/full.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/full.yml)
- [docker-compose-examples/mcp.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/mcp.yml)
- [src/client/utils/pagination.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/pagination.ts)
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
# Project Overview & Deployment
## Purpose and Scope
degoog is a self-hostable, privacy-respecting meta-search aggregator that combines results from multiple upstream search engines behind a single customizable interface. According to the project README, it is positioned as "a heavily customisable search aggregator" and a "more modular lighter alternative" to existing projects, explicitly crediting [searxng](https://github.com/searxng/searxng) as the original inspiration. Source: [README.md:1-20]()
The project's design philosophy is "you can add as much as you want to it, but the core will stay as simple as it gets." Source: [README.md:14-16]() This modularity is reflected in the source tree, which separates client rendering (for example the pagination utility in `src/client/utils/pagination.ts`) from server-side extension commands (such as the Wikipedia slot plugin in `src/server/extensions/commands/builtins/wikipedia/index.ts`).
The latest published release, referenced in community channels, is `[Stable Beta] 0.22.0`. The release notes for this version state: "This version makes having a password for settings mandatory," meaning administrative configuration is now gated by an authentication token generated on first launch. Source: community release notes (referenced in the user-provided context).
## High-Level Architecture
degoog runs as a web application composed of a TypeScript/Node backend and a browser-side renderer, with optional auxiliary services for caching and persistence. The repository ships with a `docker-compose-examples/` directory that defines several deployment topologies; each is named for the role it plays in a typical install.
The diagrams and source files reveal the following subsystems:
- **Core application container** — the degoog web service itself, serving the UI and proxying search requests to configured engines.
- **Engine layer** — pluggable search backends (e.g. Bing, DuckDuckGo, Brave) implemented as extensions loaded by the core.
- **Slot / knowledge panel layer** — built-in command plugins such as the Wikipedia summary card that render alongside results. The Wikipedia plugin, for example, queries `https:///w/api.php` with `action=query`, `prop=extracts|pageimages|pageprops|info|description`, and renders a localized template. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts:55-90]()
- **Cache layer** — optional Redis-compatible cache (Valkey in the example compose file).
- **Database layer** — optional PostgreSQL for persistence of user preferences and settings.
- **Extension store** — community-maintained plugins, themes, engines, transports, and autocomplete providers fetched from a separate repository.
```mermaid
flowchart LR
Browser[Browser Client]
Core[degoog Core
web + API]
Engines[Engine Plugins
Bing, DDG, Brave, ...]
Slots[Slot / Knowledge
Wikipedia, At-a-Glance]
Cache[(Cache
Valkey / Redis)]
DB[(Postgres
settings, prefs)]
Store[(Community
Extension Store)]
Browser <-->|HTTP / streaming| Core
Core --> Engines
Core --> Slots
Core <--> Cache
Core <--> DB
Core -.fetch.-> Store
```
This layout matches the modular structure shown in `README.md` (community extensions, plugin/theme/engine/transport separation) and the plugin code patterns seen in `src/server/extensions/commands/builtins/wikipedia/index.ts`. Source: [README.md:1-8](), [src/server/extensions/commands/builtins/wikipedia/index.ts:55-120]()
## Deployment Topologies
The `docker-compose-examples/` directory ships five reference compose files. Each one addresses a different deployment scale and use case. The names below are taken directly from the repository.
| Compose file | Intended use |
| :--- | :--- |
| [docker-compose-examples/simple.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/simple.yml) | Single-container deployment of degoog with no external dependencies — suitable for trying out the project on a laptop or small VPS. |
| [docker-compose-examples/valkey.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/valkey.yml) | Adds a [Valkey](https://valkey.io/) (Redis-compatible) sidecar to provide shared caching for instances behind a load balancer. |
| [docker-compose-examples/postgres.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/postgres.yml) | Adds a PostgreSQL sidecar for durable persistence of settings and per-user preferences. |
| [docker-compose-examples/full.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/full.yml) | Production-style stack combining Valkey and PostgreSQL with the core app. |
| [docker-compose-examples/mcp.yml](https://github.com/degoog-org/degoog/blob/main/docker-compose-examples/mcp.yml) | MCP-enabled variant exposing search to LLM agents via the Model Context Protocol. |
> Note: the exact service definitions inside each compose file were not provided in the source context for this page; the descriptions above are inferred from the file names and the README's documented feature set. Users should consult the files directly before deploying.
## Operational Notes
### Mandatory Settings Password (0.22.0+)
Beginning with the 0.22.0 release, degoog refuses to expose the settings UI without a configured password. On first startup the container prints a temporary password that must be replaced through the admin interface. Source: community release notes for `[Stable Beta] 0.22.0`.
### Extension Vetting
Community-published plugins, themes, engines, and transports live in a separate repository linked from the README. The README explicitly warns: "These have only been INITIALLY vetted, there is no way for me to keep an eye on them once they have been added to the community store repo. If your own [responsibility] to make sure what you install on your system is safe." Source: [README.md:1-8]()
### Customization Surface
Per the README, full customization is documented at `https://degoog-org.github.io/docs` and covers: plugins, themes, engines, transports, the store, the settings gate, aliases, and environment variables. Source: [README.md:10-12]()
## Community & Related Projects
The README closes with a curated comparison table of similar open-source meta-search projects, framed as "alternatives are what make the internet a fun place." Source: [README.md:14-20]()
| Project | Repository |
| :--- | :--- |
| searxng | https://github.com/searxng/searxng |
| 4get | https://git.lolcat.ca/lolcat/4get |
| OmniSearch | https://git.bwaaa.monster/omnisearch |
| LibreY | https://github.com/Ahwxorg/LibreY |
Active community discussions on the project's issue tracker focus on three recurring themes:
1. **Domain-level result filtering and replacement** — users coming from searxng have requested regex-based domain blocking and per-domain rewriting (e.g. `reddit.com` → `troddit.domain`). See issue #25.
2. **"Open in new tab" UX toggle** — a small but frequently requested UI preference. See issue #22.
3. **Maps as a result type** — parity with existing image and news result types. See issue #8.
These requests illustrate the community's desire for greater filtering control and richer result types, both of which would plug into the existing engine and slot extension architecture.
## See Also
- Wikipedia Knowledge Panel Plugin
- At-a-Glance Plugin
- Pagination Utilities
- Community Extensions Store
---
## Extension System, Store & Transports
### Related Pages
Related topics: [Project Overview & Deployment](#page-1), [Frontend, Settings UI & Onboarding](#page-4)
Related Source Files
The following source files were used to generate this page:
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [src/server/extensions/commands/builtins/wikipedia/locales/en.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/en.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/fr.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/fr.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/he.json)
- [src/server/extensions/commands/builtins/wikipedia/locales/it.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/it.json)
- [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
- [src/client/types/index.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/index.ts)
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- [src/client/utils/pagination.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/pagination.ts)
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
# Extension System, Store & Transports
## Overview
degoog ships with a modular extension framework that lets users compose a personal search aggregator out of interchangeable parts: search engines, themes, transports (HTTP primitives), autocomplete sources, and slot plugins (knowledge-panel widgets). The framework is split between **server-side registries** that load built-ins, a **community store** that serves third-party packages, and a **client-side wizard** that orchestrates the first-run setup. The project's stated goal is to be "a more modular lighter alternative" to SearXNG where the core "stays as simple as it gets." Source: [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
## Extension Categories
Per the `ExtensionMeta` interface in `src/client/types/extension.ts`, the system recognises five plug-in categories. Source: [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
| Category | Role | Typical Source |
|---|---|---|
| `engines` | Result providers / search backends | Remote services, scrapers |
| `themes` | CSS variable packs | Built-in & store |
| `transports` | Outbound HTTP primitives | Built-in (e.g. curl) & custom |
| `autocomplete` | Suggestion engines | Built-in & store |
| `shortcuts` | Quick-action entries | Store |
A separate `Command` registry holds "bang"-style triggers with optional `naturalLanguage` and `naturalLanguagePhrases`; commands expose `id`, `trigger`, and an `aliases?` array. Source: [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
Engine metadata is described by `EngineRegistry`, where each engine carries `id`, `displayName`, `primaryType`, `searchTypes[]`, and an optional `disabledByDefault` flag, plus a `defaults` map for category-level toggling. Source: [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
## The Community Store
The store is a remote package index reachable from `COMMUNITY_EXTENSIONS_URL` (referenced from the wizard), and the published docs note the URL as `degoog-org.github.io/community-extensions`. The README is candid about trust: packages are "INITIALLY vetted" only, and after publication "there is no way for me to keep an eye on them", so installation responsibility rests with the user. Source: [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
The first-run wizard walks new users through installing at least one item per category. The wizard's `storeInstallStep` factory enumerates six "must-pick" steps: **repos**, **engines**, **autocomplete**, **themes**, **plugins**, **transports**. The `requireMin` flag (e.g. `{ requireMin: 1 }` for engines) ensures the wizard blocks completion until `liveCountSelector` on `INSTALLED_GRID_SELECTOR` reports enough items. Source: [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
### Community-Discussed Limitations
Tracking issues have surfaced features that fit naturally into the store/transport model but are not visible in the supplied sources:
- **Issue #25 ("Features Request")** — asks for instance-wide **domain blocking** (preferably regex, e.g. `quora.com`, `tiktok.com`) and **domain replacement** (e.g. `reddit.com` → `troddit.domain.com`). No first-party implementation is referenced in the file excerpts.
- **Issue #22 ("Open in new tab")** — requests a default behaviour for opening result links in a new tab.
- **Issue #8 ("Maps")** — asks for a `maps` result type alongside images and news.
These would naturally land as **transport plugins** (for outbound fetchers) or **shortcut/command extensions** (for query rewriting or result-rewriting hooks).
## Plugin Lifecycle: the Wikipedia Slot Plugin
The Wikipedia extension is the canonical "slot plugin" — it renders in the knowledge-panel sidebar whenever a query matches an article. Its lifecycle is the easiest one to read end-to-end. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
```mermaid
flowchart LR
A[init ctx] --> B[trigger query?]
B -- "valid + cache hit" --> E[execute query, ctx]
B -- "valid + cache miss" --> C[fetch Wikipedia API]
C --> E
E --> F[signProxyUrl for links & thumbs]
F --> G[render template.html w/ CSS]
G --> H[knowledge panel card]
classDef plugin fill:#eef,stroke:#446;
class A,B,E plugin;
```
### Phases
1. **`init(ctx: PluginContext)`** — caches `_template`, `_signProxyUrl`, and a TTL cache handle from `ctx.useCache(WIKI_NAMESPACE, WIKI_TTL_MS)`. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
2. **`trigger(query)`** — quick boolean gate; rejects empty/short (<2) or overly long (>100) queries and returns `false` if the cache misses *and* the upstream fetch fails. Source: [src/server/extensions/commands/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
3. **`execute(query, ctx?)`** — fetches the page (with `exintro=1`, `explaintext=1`, `exsentences=6`, `pithumbsize=300`, `redirects=1`), optionally follows the `wikibase_item` to grab a Wikidata thumbnail, then renders the template. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
### Settings
User-facing configuration is declared declaratively as `settingsSchema: SettingField[]`. Wikipedia exposes a single `text` field (`"Wikipedia domain"`) with `default: DEFAULT_WIKI_DOMAIN`; any value that is not a `*.wikipedia.org` host falls back to `en.wikipedia.org`. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
### Localisation & Style
Plugins carry their own per-locale JSON. Wikipedia publishes translations for at least `en`, `fr`, `he`, and `it`, each with the keys `name`, `description`, and `view-on-wikipedia`. Sources: [locales/en.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/en.json), [locales/fr.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/fr.json), [locales/he.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/he.json), [locales/it.json](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/locales/it.json). The plugin also ships a scoped `style.css` so the host UI doesn't need to know how to lay it out. Source: [style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
The HTML skeleton (`template.html`) uses `target="_blank" rel="noopener noreferrer"` on outbound links — relevant context for **Issue #22**'s "open in new tab" discussion. Source: [template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
## Common Failure Modes
- **Domain validation** — non-`*.wikipedia.org` values silently fall back, so a typo will look like a working config but always render English. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- **Trigger length bound** — queries <2 or >100 chars return `false`, suppressing the panel; useful to know when debugging "why isn't my card showing up?"
- **Wikidata thumbnail fetch** — bounded by an `AbortController` with `TIMEOUT_MS`; on failure the plugin returns `undefined` thumbnail without retrying.
- **Cache invalidation** — content is keyed by `host + lowercased query` and stored with `WIKI_TTL_MS`; expect stale extracts after server-side edits until the TTL elapses.
- **Missing translation** — locales not shipped with the plugin fall back to raw keys (visible in `plugins.t("...")` resolution paths used by slot plugins).
## See Also
- Tab-level search integration that consumes slot panels: [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- Pagination helper used by extension-rendered result lists: [src/client/utils/pagination.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/pagination.ts)
- Cross-cutting type barrels: [src/client/types/index.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/index.ts)
---
## Search Backend, Indexer & Data Flow
### Related Pages
Related topics: [Project Overview & Deployment](#page-1), [Extension System, Store & Transports](#page-2)
Related Source Files
The following source files were used to generate this page:
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/builtins/at-a-glance/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/at-a-glance/index.ts)
- [src/client/utils/search/search-actions-page.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/search/search-actions-page.ts)
- [src/client/modules/renderer/render.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render.ts)
- [src/client/modules/renderer/render-sidebar.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render-sidebar.ts)
- [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
# Search Backend, Indexer & Data Flow
## Overview and Scope
degoog is a privacy-respecting meta-search engine that aggregates results from multiple upstream engines. According to the [README.md](README.md), the project draws inspiration from searxng, 4get, OmniSearch, and LibreY, and exposes a modular backend with plug-in "slots" that enrich the sidebar.
The **Search Backend, Indexer & Data Flow** layer in degoog is responsible for:
- Receiving a query (with optional page number, type, and per-tab state).
- Coordinating upstream engine fan-out and result scoring.
- Returning a normalized response to the client.
- Driving sidebar "knowledge panels" (Wikipedia, At-a-glance, etc.) through the slot plugin system.
Because degoog is a meta-search engine rather than a crawler-based index, the term "indexer" refers to the in-process result aggregation, deduplication, scoring, and the per-slot `AsyncTtlCache` used to memoize upstream fetches.
## High-Level Data Flow
A search proceeds through three logical stages: client dispatch → server fan-out → client render with sidebar enrichment.
```mermaid
flowchart LR
A[Client Tab / Page Action] --> B[Search POST/GET]
B --> C[Server Search Backend]
C --> D[Engine Selection & Fan-out]
D --> E[Result Aggregation & Scoring]
E --> F[Slot Plugins: Wikipedia, At-a-glance]
F --> G[Normalized SearchResponse]
G --> H[renderResults + prependKnowledgePanels]
H --> I[DOM: results-list + results-sidebar]
```
The client initiates the round-trip from two places: a regular paginated request via `goToPage` (see `search-actions-page.ts`), and a tab-scoped request via `performTabSearch` in `tab-search.ts`. Both build a query body and POST it to `/api/search`. Pagination toggles skeleton placeholders first (`skeletonImageGrid` or `skeletonResults`) so the UI feels responsive even when the upstream engines are slow. Source: [src/client/utils/search/search-actions-page.ts:18-30]()
## Slot Plugin System (The "Indexer" of Sidebar Knowledge)
The closest analog to a backend indexer in degoog is the **slot plugin** framework that decorates the response with structured sidebar panels. Each slot plugin implements `SlotPlugin` and is positioned in the sidebar via `SlotPanelPosition.KnowledgePanel`.
### Wikipedia Slot
The Wikipedia slot, defined in [`wikipedia/index.ts`](src/server/extensions/commands/builtins/wikipedia/index.ts), fetches a summary card when the user query matches an article title.
- **Trigger gate**: queries are accepted only if length is between 2 and 100 characters (`index.ts`, `trigger()`).
- **Domain setting**: configurable via the `domain` setting; defaults to `en.wikipedia.org` and must be a `*.wikipedia.org` host. Invalid hosts fall back to the default.
- **Cache**: an `AsyncTtlCache` is allocated through `ctx.useCache(WIKI_NAMESPACE, WIKI_TTL_MS)`, providing per-(host, query) memoization to avoid hammering Wikipedia.
- **Upstream calls**: the main fetch hits `https://{host}/w/api.php` with `action=query`, `prop=extracts|pageimages|pageprops|info|description`, requesting `exsentences=6` and `pithumbsize=300`. If no thumbnail is returned, a follow-up Wikidata call (`wbgetentities`) is issued to recover a logo. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts:115-160]()
- **Rendering**: the server returns an HTML string rendered from [`template.html`](src/server/extensions/commands/builtins/wikipedia/template.html) using `_template`, styled by [`style.css`](src/server/extensions/commands/builtins/wikipedia/style.css). Thumbnail and external links are signed via `signProxyUrl` so the client never sees raw third-party URLs.
- **i18n**: localized strings live under `locales/{en,fr,it,he}.json`.
### At-a-glance Slot
The At-a-glance slot, in [`at-a-glance/index.ts`](src/server/extensions/commands/builtins/at-a-glance/index.ts), picks the best result from the ranked list and shows a short preview in the sidebar.
- It selects the best result with `_pickBestResult()`, optionally demoting results that are already covered by the Wikipedia panel.
- It can either use the engine-provided `snippet` or (when `fetchContent` is enabled) request a deeper extraction through `context.fetch`, with a configurable timeout and `excerptMode`.
- Excerpt length and paragraph count are bounded by `settings.maxLength` and `settings.maxParagraphs` to keep the sidebar compact.
This slot illustrates how degoog composes sidebar content without maintaining its own crawl index: it piggybacks on whatever the upstream engines and the at-the-time fetched page return.
## Client-Side Rendering Pipeline
Once the server response arrives, the client renders the main list and the sidebar.
- `renderResults` in [`render.ts`](src/client/modules/renderer/render.ts) builds the HTML for the ranked list, including per-result action flags (block, replace, score) exposed via `window.__DEGOOG_RESULT_ACTIONS__`. The flags are gated on `authenticated`, `blockUi`, `replaceUi`, and `scoreUi` — these correspond to community feature requests like domain blocking and result replacement (see issue #25).
- `renderSidebar` and `prependKnowledgePanels` in [`render-sidebar.ts`](src/client/modules/renderer/render-sidebar.ts) compose the sidebar. `prependKnowledgePanels` injects slot panels at the top of `#results-sidebar` wrapped in a `sidebarAccordion`, and auto-opens them on screens `>= 768px` for desktop layouts.
- Related searches and engine performance metrics are appended lower in the sidebar, while the slot panels dominate the "above the fold" experience — directly responding to feedback like issue #22 ("Open in new tab") because the panel links use `target="_blank"` and `rel="noopener noreferrer"` in `template.html`.
The first-paint sequence for a tab search is therefore: skeleton → server fetch → `prependKnowledgePanels` (Wikipedia/At-a-glance) → `renderResults` → image/media observer setup → `renderMediaEngineBar`.
## Configuration, Extension Points, and Limits
The slot plugin system is wired up through a wizard that walks new users through engine, autocomplete, theme, plugin, and transport installation (`steps.ts`). Slot plugins are first-class extensions: any plugin registered with `SlotPanelPosition.KnowledgePanel` automatically appears in the sidebar without further client changes, provided it returns `{ html, title? }` from `execute()`.
Common failure modes observed in the source:
| Failure | Source behavior |
| --- | --- |
| Query too short or too long | `trigger()` returns `false`; the slot silently opts out. |
| Wikipedia page missing | `_fetchWikipedia` returns `null`; cache key is not stored. |
| Non-`*.wikipedia.org` host | Domain validation in `_wikiDomain()` falls back to `en.wikipedia.org`. |
| Upstream timeout | Each fetch is wrapped in an `AbortController` with `TIMEOUT_MS`; the slot returns `null` and logs at `debug` level. |
| Thumbnail missing on Wikipedia | Fallback to Wikidata `wbgetentities` to recover a logo. |
For end-user feature requests (e.g., maps in issue #8, "open in new tab" in #22, or domain blocking/replacement in #25), the relevant extension points are the per-result action flags (`ResultActionsFlags`) injected into the result template, and additional slot plugins that can contribute to the same sidebar surface.
## See Also
- Slot plugin authoring guide (SlotPlugin interface, settingsSchema, init/execute contract)
- Settings & authentication model (the 0.22.0 release introduced mandatory settings passwords)
- Engine selection and upstream fan-out
- Streaming search configuration
---
## Frontend, Settings UI & Onboarding
### Related Pages
Related topics: [Project Overview & Deployment](#page-1), [Extension System, Store & Transports](#page-2), [Search Backend, Indexer & Data Flow](#page-3)
Related Source Files
The following source files were used to generate this page:
- [src/client/modules/wizard/steps.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts)
- [src/client/types/extension.ts](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts)
- [src/client/modules/renderer/render-sidebar.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render-sidebar.ts)
- [src/client/modules/tabs/tab-search.ts](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts)
- [src/client/utils/pagination.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/pagination.ts)
- [src/client/utils/search/search-actions-page.ts](https://github.com/degoog-org/degoog/blob/main/src/client/utils/search/search-actions-page.ts)
- [src/client/animations/skeleton.ts](https://github.com/degoog-org/degoog/blob/main/src/client/animations/skeleton.ts)
- [src/server/extensions/commands/builtins/wikipedia/index.ts](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts)
- [src/server/extensions/commands/builtins/wikipedia/template.html](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html)
- [src/server/extensions/commands/builtins/wikipedia/style.css](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css)
- [README.md](https://github.com/degoog-org/degoog/blob/main/README.md)
# Frontend, Settings UI & Onboarding
## Overview
degoog is a heavily customisable search aggregator whose client side is organised around three cooperating systems: a **typed settings UI** that renders every extension's configuration form from a single schema, an **onboarding wizard** that walks first-time users through engine and store installation, and a **rendering pipeline** that combines search results, pagination, slot-panel knowledge cards, and skeleton placeholders into the main view. The client uses TypeScript module boundaries (`src/client/modules/...`, `src/client/utils/...`) and pulls additional content such as Wikipedia knowledge panels from server-side **slot plugins** rendered into the sidebar. The full customisation guide is published externally and is linked from the README ([README.md:6-10](https://github.com/degoog-org/degoog/blob/main/README.md)).
```mermaid
flowchart LR
User[User / Browser] --> App[Client App State]
App --> Settings[Settings UI
renders SettingField schemas]
App --> Wizard[Onboarding Wizard
steps.ts]
Wizard --> Store[Community Extensions Store]
Settings --> Engines[Engine / Plugin / Theme
extensions]
App --> TabSearch[Tab Search Orchestrator]
TabSearch --> Pagination[Pagination Builder]
TabSearch --> Skeleton[Skeleton Placeholders]
TabSearch --> Sidebar[Sidebar Renderer]
Sidebar --> SlotPanels[Slot Plugin Knowledge Panels
e.g. Wikipedia]
```
## Settings UI & Extension Schema
The settings UI is data-driven: every extension exposes a `settingsSchema` array whose entries conform to the `SettingField` interface, and the renderer maps each entry to an appropriate form control. The supported input types are listed in `SettingFieldType`:
| Type | Purpose |
| :--------- | :------------------------------------------ |
| `text` | Single-line string input (e.g. Wikipedia domain) |
| `number` | Numeric input |
| `password` | Masked secret (required for the settings gate from 0.22.0 onward) |
| `url` | URL input |
| `toggle` | Boolean switch |
| `textarea` | Multi-line text |
| `select` | Single-choice from `options[]` |
| `urllist` | Repeatable URL list |
| `list` | Repeatable generic list driven by `itemSchema` |
| `info` | Read-only help text |
Source: [src/client/types/extension.ts:1-19](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts).
Each `ExtensionMeta` aggregates an extension's identity, capabilities, and its already-resolved `settings: Record` so the UI can render pre-populated forms without an extra round-trip. Fields such as `visibleWhen`, `advanced`, `secret`, `required`, `placeholder`, `default`, and `optionLabels` give extension authors fine-grained control over how and when controls appear. Source: [src/client/types/extension.ts:21-49](https://github.com/degoog-org/degoog/blob/main/src/client/types/extension.ts).
A concrete example is the **Wikipedia** slot plugin, whose single setting is a free-form domain field defaulting to `en.wikipedia.org`. The schema explicitly validates that the value is a `*.wikipedia.org` host and falls back otherwise. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts:43-56](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts).
## Onboarding Wizard
The wizard is implemented as a statically-declared list of steps in `src/client/modules/wizard/steps.ts`. Each step targets either a settings tab (selected via a CSS selector on `.settings-nav-item[data-tab="..."]`) or a contextual popover anchored to a specific UI region. Store-related steps build on a shared helper `storeInstallStep(...)` that highlights an install grid and can require a minimum live count via `liveCountSelector` / `requireMin`. Source: [src/client/modules/wizard/steps.ts:18-49](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts).
The sequence covers five store categories — **repositories**, **engines** (which must reach at least one installed engine via `requireMin: 1`), **autocomplete providers**, **themes**, **plugins**, and **transports** — followed by guided tours of the **engines**, **autocomplete**, and **server** tabs, a security link to the environment documentation, and a closing "done" step. Source: [src/client/modules/wizard/steps.ts:51-93](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts).
The wizard references the community store URL `COMMUNITY_EXTENSIONS_URL` for the repositories step and links the security step out to `https://degoog-org.github.io/docs/env.html`. Source: [src/client/modules/wizard/steps.ts:1-17](https://github.com/degoog-org/degoog/blob/main/src/client/modules/wizard/steps.ts). Combined with the 0.22.0 release note in the community context — which makes a settings password mandatory and prints a temporary password at startup — the wizard and the settings gate are the primary paths to first-time configuration.
## Sidebar, Slot Panels & Knowledge Cards
The sidebar is rendered by `render-sidebar.ts`, which composes engine-stat accordions, related searches, and any incoming slot panels. The function `prependKnowledgePanels(panels: SlotPanel[])` inserts each panel's HTML at the **top** of `#results-sidebar` wrapped in a `sidebarAccordion(...)`, then auto-opens every accordion on viewports ≥ 768 px so desktop users immediately see context. Source: [src/client/modules/renderer/render-sidebar.ts:171-184](https://github.com/degoog-org/degoog/blob/main/src/client/modules/renderer/render-sidebar.ts).
Slot plugins are server-side modules that decide when they should appear (`trigger`) and what HTML to render (`execute`). The Wikipedia plugin, for instance, registers `SlotPanelPosition.KnowledgePanel` and exposes `isClientExposed: false`, meaning its trigger and rendering run on the server. It accepts queries between 2 and 100 characters, keys its `AsyncTtlCache` on `host:query`, and returns `null` on miss/error so the client can silently skip the panel. Source: [src/server/extensions/commands/builtins/wikipedia/index.ts:57-73](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts). If the MediaWiki API response lacks a thumbnail, it follows up with a Wikidata `wbgetentities` call to fetch a logo. Source: [src/server/extensions/commands/commands/builtins/wikipedia/index.ts:148-167](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/index.ts).
The knowledge-card template is a plain HTML string with `{{title}}`, `{{url}}`, `{{description}}`, `{{extract}}`, and `{{thumbnail}}` placeholders that the server substitutes before sending to the client. Source: [src/server/extensions/commands/builtins/wikipedia/template.html:1-19](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/template.html). Styling for `.wiki-card`, `.wiki-title`, `.wiki-extract`, `.wiki-thumb`, and `.wiki-footer-link` lives in the plugin's own `style.css`, keeping slot assets co-located with their plugin. Source: [src/server/extensions/commands/builtins/wikipedia/style.css:1-50](https://github.com/degoog-org/degoog/blob/main/src/server/extensions/commands/builtins/wikipedia/style.css).
## Search Results, Pagination & Loading States
Tab-scoped searches are orchestrated by `performTabSearch(query, tabId, page)` in `src/client/modules/tabs/tab-search.ts`, which clears previous state, swaps in skeleton markup via `skeletonImageGrid` / `skeletonResults`, fetches a streaming config, and then triggers `performStreamingSearch`. It also kicks off side fetches for glance panels and slot panels so they arrive in parallel with the result stream. Source: [src/client/modules/tabs/tab-search.ts:30-55](https://github.com/degoog-org/degoog/blob/main/src/client/modules/tabs/tab-search.ts).
Pagination is built by `buildPaginationHtml(totalPages, activePage)` which clamps a window of at most 10 page links, anchoring it around the active page and emitting either a `