# algolia/docsearch architecture

> Architecture diagram of the GitHub repository algolia/docsearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/algolia/docsearch
- Repository: https://github.com/algolia/docsearch

## Overview

##### Project type and purpose
- This is an open-source monorepo providing:
- A standalone JavaScript search widget (`@docsearch/js`)
- A React search component (`@docsearch/react`)
- A CSS package for styling (`@docsearch/css`)
- A documentation website built with Docusaurus (`packages/website`)
- Several example integrations/demos
- It crawls doc sites, pushes content to an Algolia index, and renders a dropdown search UI.

##### File structure
- Top-level:
- CI/CD configs (`.circleci/`, `.github/workflows`, `netlify.toml`)
- Monorepo config (`lerna.json`, Yarn workspace files)
- Build/tooling (`rollup.base.config.js`, `vite.config.mts`, Babel configs)
- `packages/`: four main workspaces (docsearch‐css, docsearch‐js, docsearch‐react, website)
- `examples/`: end-user integration samples (React, JS)
- `cypress/`: E2E test suite
- Scripts for bundling, testing, publishing (`scripts/`)
- Patterns & tools:
- Monorepo with Lerna & Yarn workspaces
- Build pipelines via Rollup/Babel/Vite
- Testing: Jest for unit, Cypress for E2E
- Deployment: Netlify for website, npm registry for packages

##### README insights
- Core function: “crawl docs → push to Algolia → provide search UI”
- Distinct usage flows: JavaScript vs React
- References to external endpoints (Algolia API, CDN) and deployment badges

##### Main components & interactions
A. Monorepo root
- Orchestrates package builds, tests, and publishing via Lerna + Yarn
B. Package workspaces
1. docsearch-css: styling assets (CSS variables, modal, button)
2. docsearch-js: vanilla JS implementation, bundles via Rollup
3. docsearch-react: React UI components, hooks, tests, bundles via Rollup
4. website: Docusaurus static site, docs pages, custom plugins, deployed on Netlify
C. Examples
- Demo apps illustrating usage of `@docsearch/js` and `@docsearch/react`
- Hosted/previewed via CodeSandbox or local dev server (Vite)
D. External services
- Algolia Search API (appId, apiKey, indexName)
- npm registry (publishing packages)
- Netlify (website CI/CD)
- GitHub Actions / CircleCI (CI for tests & publishing)

Interactions:
- Developer pushes code → CI runs Lerna bootstrap → builds each package → runs Jest + Cypress → on success, publishes packages to npm + deploys website to Netlify
- End user imports `@docsearch/js` or `@docsearch/react` → library instantiates search UI → issues queries to Algolia Search API → receives hits → renders dropdown UI styled by docsearch-css

##### Architectural patterns & design principles
- Monorepo/workspace pattern for code sharing and versioning
- Separation of concerns: styling, behavior (JS), UI (React), docs site
- CI/CD gating (unit + E2E) before publishing
- Modular build strategy: Rollup configs per package, Vite for demos

##### Key details to capture
- The four workspace packages and their roles
- Monorepo orchestration and CI/CD flow
- Consumption flow: library → Algolia → UI
- Deployment targets: npm registry & Netlify
- Testing layers: unit vs E2E

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo control plane
    Root["Monorepo Root<br/>(Lerna + Yarn Workspaces)"]:::root

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        CircleCI["CircleCI"]:::ci
        GitHubActions["GitHub Actions"]:::ci
        NetlifyCI["Netlify (Deploy Website)"]:::ci
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        Rollup["rollup.base.config.js"]:::tooling
        ViteConfig["vite.config.mts"]:::tooling
        subgraph "Babel Configs"
            BabelJS["docsearch-js babel.config.mjs"]:::tooling
            BabelReact["docsearch-react babel.config.mjs"]:::tooling
            BabelSite["website babel.config.mjs"]:::tooling
        end
    end

    %% Packages workspace
    subgraph "Packages"
        CSS["docsearch-css"]:::code
        JS["docsearch-js"]:::code
        ReactPkg["docsearch-react"]:::code
        Website["website"]:::code
    end

    %% Examples / Demos
    subgraph "Examples"
        ReactDemo["React Demo (Vite)"]:::example
        LegacyDemo["React Legacy Demo"]:::example
        JSDemo["Vanilla JS Demo"]:::example
    end

    %% Testing & Scripts
    Cypress["E2E Testing (Cypress)"]:::tooling
    Scripts["Utility & Helper Scripts"]:::tooling
    TSConfig["TypeScript Configurations"]:::tooling

    %% External services
    NPM["npm Registry"]:::external
    Algolia["Algolia Search API"]:::external

    %% Relationships
    Root -->|"orchestrates build/test/publish"| CircleCI
    Root -->|bootstraps| GitHubActions
    CircleCI -->|"on success publishes"| NPM
    GitHubActions -->|"on success deploys"| NetlifyCI
    Root -->|uses| Rollup
    Root -->|uses| ViteConfig
    Root -->|uses| BabelJS
    Root -->|uses| BabelReact
    Root -->|uses| BabelSite
    Root -->|"runs tests via"| Cypress
    Root -->|"runs helpers"| Scripts
    Root -->|"configs"| TSConfig

    Root -->|"manages workspaces"| CSS
    Root -->|"manages workspaces"| JS
    Root -->|"manages workspaces"| ReactPkg
    Root -->|"manages workspaces"| Website

    ReactDemo -->|"imports"| ReactPkg
    LegacyDemo -->|"imports"| ReactPkg
    JSDemo -->|"imports"| JS

    JS -->|"issues queries"| Algolia
    ReactPkg -->|"issues queries"| Algolia

    Website -->|"consumes packages"| CSS
    Website -->|"consumes packages"| JS
    Website -->|"consumes packages"| ReactPkg
    Website -->|"deployed by"| NetlifyCI

    %% Click events
    click Root "https://github.com/algolia/docsearch/blob/main/lerna.json"
    click CircleCI "https://github.com/algolia/docsearch/blob/main/.circleci/config.yml"
    click GitHubActions "https://github.com/algolia/docsearch/blob/main/.github/workflows/renovate.yml"
    click NetlifyCI "https://github.com/algolia/docsearch/blob/main/netlify.toml"
    click Rollup "https://github.com/algolia/docsearch/blob/main/rollup.base.config.js"
    click ViteConfig "https://github.com/algolia/docsearch/blob/main/vite.config.mts"
    click BabelJS "https://github.com/algolia/docsearch/blob/main/packages/docsearch-js/babel.config.mjs"
    click BabelReact "https://github.com/algolia/docsearch/blob/main/packages/docsearch-react/babel.config.mjs"
    click BabelSite "https://github.com/algolia/docsearch/blob/main/packages/website/babel.config.mjs"
    click CSS "https://github.com/algolia/docsearch/tree/main/packages/docsearch-css/"
    click JS "https://github.com/algolia/docsearch/tree/main/packages/docsearch-js/"
    click ReactPkg "https://github.com/algolia/docsearch/tree/main/packages/docsearch-react/"
    click Website "https://github.com/algolia/docsearch/tree/main/packages/website/"
    click ReactDemo "https://github.com/algolia/docsearch/tree/main/examples/demo-react-18/"
    click LegacyDemo "https://github.com/algolia/docsearch/tree/main/examples/demo/"
    click JSDemo "https://github.com/algolia/docsearch/tree/main/examples/js-demo/"
    click Cypress "https://github.com/algolia/docsearch/blob/main/cypress.config.ts"
    click Scripts "https://github.com/algolia/docsearch/blob/main/scripts/setupTests.ts"
    click TSConfig "https://github.com/algolia/docsearch/blob/main/tsconfig.json"

    %% Styles
    classDef root fill:#f9f,stroke:#333,stroke-width:2px;
    classDef code fill:#fffbcc,stroke:#333,stroke-width:1px;
    classDef ci fill:#cfffcf,stroke:#333,stroke-width:1px;
    classDef tooling fill:#e0ccff,stroke:#333,stroke-width:1px;
    classDef example fill:#ccf2ff,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcccc,stroke:#333,stroke-width:1px;
```
