# openbb-finance/openbb-docs architecture

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

- Interactive diagram: https://gitdiagram.com/openbb-finance/openbb-docs
- Repository: https://github.com/openbb-finance/openbb-docs

## Overview

##### Project type and purpose
- This is a documentation website built with Docusaurus (a React-based static site generator) and styled with TailwindCSS.
- Its role is to consume markdown content (in the `content` directory), React components (in `src`), and static assets, build a static site, and deploy it via GitHub Pages.
- It also integrates Algolia for search, uses Python scripts to generate or preprocess markdown, and employs GitHub Actions for CI/CD.

##### File structure
- Top-level directories:
- `content` (all `.md`/`.mdx` documentation grouped by product areas: bot, cli, excel, platform, workspace…)
- `scripts` (Python scripts to auto-generate or update markdown)
- `src` (custom React components and theme overrides for the Docusaurus site)
- `static` (static files—images, KaTeX assets, CNAME)
- `.github/workflows/deploy-gh-pages.yml` (CI/CD pipeline for building and publishing)
- Key config files: `docusaurus.config.ts`, `sidebars.js`, `tailwind.config.ts`, `package.json`, `babel.config.cjs`
- Build targets: local dev server (`npm start`), production static build (`npm run build` → `build/`), deploy to `gh-pages` branch.
- External integrations: Algolia search, GitHub Pages hosting, Python interpreter for scripts.

##### README for additional insights
- Confirms usage of Node.js ≥16.13.0, Docusaurus, TailwindCSS, Algolia.
- Describes the content pipeline: Python scripts generate markdown in `content`; markdown is consumed by Docusaurus.
- CI: GitHub Actions builds on push and deploys to GitHub Pages.
- Tests: pytest for platform docs validation.

a. Main components
- Content Authoring Layer
- Markdown files (`content/`)
- Python scripts (`scripts/`)
- Presentation Layer
- Custom React components & themes (`src/`)
- Docusaurus framework (SSG engine)
- TailwindCSS styling
- Build & Deployment Pipeline
- Node.js runtime
- `npm install` / `npm run build`
- GitHub Actions workflow
- Hosting & Delivery
- GitHub Pages (static site hosting, CDN)
- External Services
- Algolia Search API
b. Relationships & data flows
1. Developer edits or generates markdown (`content/`) or React components (`src/`).
2. Python scripts preprocess or generate markdown files.
3. Docusaurus (via Node.js) reads `content/`, `src/`, and `docusaurus.config.ts`, applies theme and CSS, and outputs static HTML/CSS/JS.
4. GitHub Actions triggers on repo push, runs `npm run build`, and publishes the `build/` directory to the `gh-pages` branch.
5. End users access the site via GitHub Pages CDN. Runtime search requests from the client go to Algolia’s API.
c. Architectural patterns & principles
- Static Site Generation (SSG) for performance and security.
- Component-based UI (React) with theme overrides.
- Content-as-code: documentation stored and versioned alongside code.
- CI/CD via GitHub Actions.
- Separation of concerns: content (Markdown), presentation (React/TSX + CSS), build (Node), and deployment (GitHub Pages).
d. Key technologies & libraries
- Docusaurus (React SSG)
- React / TypeScript for theming and interactive components
- TailwindCSS
- Python (markdown generation scripts)
- GitHub Actions (CI/CD)
- Algolia (search)
- GitHub Pages (hosting)

##### Final advice
- Be comprehensive: include all folders or modules only if they play a distinct architectural role (e.g., `scripts/` vs. `src/components/`).
- Data flow, build flow, and runtime interactions.
- Review with content authors and DevOps to ensure nothing is missed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Authoring Layer
    subgraph "Content Authoring Layer"
        direction TB
        MC["Markdown Content"]:::content
        subgraph "Python Preprocessing Scripts"
            direction TB
            GP1["generate_excel_markdown.py"]:::python
            GP2["generate_platform_markdown.py"]:::python
            GP3["generate_widgets_library.py"]:::python
        end
    end

    %% Presentation & Build Layer
    subgraph "Presentation & Build"
        direction TB
        subgraph "Docusaurus Configuration"
            direction TB
            DC1["docusaurus.config.ts"]:::config
            DC2["sidebars.js"]:::config
            DC3["tailwind.config.ts"]:::config
            DC4["babel.config.cjs"]:::config
            VS1["version-v3-sidebars.json"]:::config
            VS2["versions.json"]:::config
        end
        subgraph "Custom UI Components & Styles"
            direction TB
            CRC["src/components/"]:::react
            TO["src/theme/"]:::react
            GS["src/css/custom.css"]:::css
            CP["src/pages/"]:::pages
            SA["static/"]:::static
        end
        DSSG["Docusaurus SSG (Node.js)"]:::build
        TC["TailwindCSS Engine"]:::build
    end

    %% External Integration
    subgraph "External Integration"
        direction TB
        AC["initialAlgoliaCrawler.js"]:::external
        Algolia["Algolia Search API"]:::external
    end

    %% CI/CD Pipeline
    subgraph "Build & Deployment Pipeline"
        direction TB
        CI["deploy-gh-pages.yml"]:::ci
        Tests["test_platform_docs.py"]:::tests
    end

    %% Hosting & Delivery
    GH["GitHub Pages (CDN)"]:::hosting
    User["End User Browser"]:::user

    %% Relationships
    GP1 -->|generates| MC
    GP2 -->|generates| MC
    GP3 -->|generates| MC
    MC -->|"content + config"| DSSG
    CRC -->|"components + theme"| DSSG
    TO -->|"theme overrides"| DSSG
    GS -->|"styles"| DSSG
    CP -->|"custom pages"| DSSG
    SA -->|"assets"| DSSG
    DC1 -->|"configures"| DSSG
    DC2 -->|"sidebar info"| DSSG
    DC3 -->|"Tailwind setup"| TC
    TC -->|"styles injection"| DSSG
    VS1 -->|"versioned sidebar"| DSSG
    VS2 -->|"versions metadata"| DSSG

    DSSG -->|"npm run build"| BuildOutput["build/"]:::build
    BuildOutput -->|"publish"| GH
    CI -->|"on push build & deploy"| DSSG
    Tests -->|"validate docs"| DSSG

    User -->|visits site| GH
    User -->|search queries| Algolia
    AC -->|"update search index"| Algolia

    %% Click Events
    click MC "https://github.com/openbb-finance/openbb-docs/tree/main/content/"
    click GP1 "https://github.com/openbb-finance/openbb-docs/blob/main/scripts/generate_excel_markdown.py"
    click GP2 "https://github.com/openbb-finance/openbb-docs/blob/main/scripts/generate_platform_markdown.py"
    click GP3 "https://github.com/openbb-finance/openbb-docs/blob/main/scripts/generate_widgets_library.py"
    click DC1 "https://github.com/openbb-finance/openbb-docs/blob/main/docusaurus.config.ts"
    click DC2 "https://github.com/openbb-finance/openbb-docs/blob/main/sidebars.js"
    click DC3 "https://github.com/openbb-finance/openbb-docs/blob/main/tailwind.config.ts"
    click DC4 "https://github.com/openbb-finance/openbb-docs/blob/main/babel.config.cjs"
    click VS1 "https://github.com/openbb-finance/openbb-docs/blob/main/versioned_sidebars/version-v3-sidebars.json"
    click VS2 "https://github.com/openbb-finance/openbb-docs/blob/main/versions.json"
    click CRC "https://github.com/openbb-finance/openbb-docs/tree/main/src/components/"
    click TO "https://github.com/openbb-finance/openbb-docs/tree/main/src/theme/"
    click GS "https://github.com/openbb-finance/openbb-docs/blob/main/src/css/custom.css"
    click CP "https://github.com/openbb-finance/openbb-docs/tree/main/src/pages/"
    click SA "https://github.com/openbb-finance/openbb-docs/tree/main/static/"
    click CI "https://github.com/openbb-finance/openbb-docs/blob/main/.github/workflows/deploy-gh-pages.yml"
    click AC "https://github.com/openbb-finance/openbb-docs/blob/main/utils/initialAlgoliaCrawler.js"
    click Tests "https://github.com/openbb-finance/openbb-docs/blob/main/tests/test_platform_docs.py"

    %% Styles
    classDef content fill:#E0F7FA,stroke:#006064
    classDef python fill:#FFF3E0,stroke:#E65100
    classDef config fill:#E8F5E9,stroke:#1B5E20
    classDef react fill:#E3F2FD,stroke:#0D47A1
    classDef css fill:#F3E5F5,stroke:#4A148C
    classDef static fill:#ECEFF1,stroke:#263238
    classDef pages fill:#F1F8E9,stroke:#33691E
    classDef build fill:#FFFDE7,stroke:#F57F17
    classDef ci fill:#F9FBE7,stroke:#827717
    classDef tests fill:#FFEBEE,stroke:#B71C1C
    classDef external fill:#FFF8E1,stroke:#FF6F00
    classDef hosting fill:#E8EAF6,stroke:#1A237E
    classDef user fill:#FFEBEE,stroke:#B71C1C
```
