# nillionnetwork/nillion-docs architecture

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

- Interactive diagram: https://gitdiagram.com/nillionnetwork/nillion-docs
- Repository: https://github.com/nillionnetwork/nillion-docs

## Overview

##### Primary Components
- Documentation Content: The core of the system, which lives in the docs directory, organizes all the textual guides, tutorials, community information, and various API documentation sections.
- API Specifications: The apispec folder contains OpenAPI/YAML files for defining several APIs (for “nilai” and “nildb”). These represent the contract layer for external (or internal) API usage.
- Source Code & Components: The src directory houses React components (such as homepage features, navigation elements, interactive components) that render the documentation pages.
- Static Assets: The static folder holds images, fonts, and additional JS files that support the UI.
- Configuration & Build Artifacts: Files like docusaurus.config.js, sidebar.js, babel.config.js, and package.json define the configuration/settings and build instructions.
- CI/CD & Deployment: GitHub workflows (in .github/workflows) and vercel.json provide instructions for automated builds, tests, and deployment to docs.nillion.com.

##### Interactions and Data Flow
- Content and Layout Flow: Markdown/MDX content from the docs folder is processed via Docusaurus (configured in docusaurus.config.js and sidebars files) to create a static site.
- React Components: The src components get rendered into the static content; they pull in content, apply styling (via CSS modules in src/css), and may incorporate dynamic elements (like API-driven search using Algolia DocSearch).
- API Integration: The API spec files (in apispec) indicate how APIs are defined and possibly referenced in the documentation. They can be linked from the docs, showing their relationship to component explanations.
- Build and Deployment Pipeline: The Yarn commands (yarn install, yarn start, yarn build) trigger a pipeline that compiles the React app, processes documentation content, and outputs static files. These are then deployed via Vercel as indicated by the vercel.json.
- CI/CD Integration: GitHub Actions (workflows in .github) sync branches (like main to release) and manage continuous integration/deployment steps.

##### Architectural Patterns and Key Technologies
- Static Site Generation (SSG): Docusaurus v3 processes markdown documents and React components to produce a static website.
- Modular Component Architecture: The separation between content (docs), presentation logic (src/components and src/theme), and configuration promotes modular design.
- OpenAPI Specifications: The API documentation defined in YAML in the apispec folder is used to clearly document and potentially test API endpoints.
- CI/CD Pipeline: The project uses GitHub Workflows for automated testing and builds along with deployment via Vercel.
- Integration with External Services: Algolia DocSearch is integrated to provide a search feature across the documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    subgraph "Content Layer"
        docs["Docs (Markdown Content)"]:::content
        apispec["API Specifications (OpenAPI YAML)"]:::content
    end

    %% Application/Presentation Layer
    subgraph "Application/Presentation Layer"
        react["React Components"]:::component
        static["Static Assets"]:::asset
        docusaurus["Docusaurus Build Engine (SSG)"]:::build
        subgraph "Configuration & Build Artifacts"
            docusConfig["docusaurus.config.js"]:::config
            babelConfig["babel.config.js"]:::config
            packageNode["package.json"]:::config
            sidebarNode["sidebars.js"]:::config
        end
        algolia["Algolia DocSearch"]:::external
    end

    %% Build & Deployment Pipeline
    subgraph "Build & Deployment Pipeline"
        buildProc["Local Build (Yarn Start/Build)"]:::buildproc
        subgraph "CI/CD & Deployment"
            workflows["GitHub Actions (.github/workflows/)"]:::ci
            vercelConfig["Deployment Config (vercel.json)"]:::ci
            vercelHost["Deployment (Vercel Hosting)"]:::external
        end
    end

    %% End User
    browser["User Browser"]:::external

    %% Connections: Content to Build Engine
    docs -->|"feeds"| docusaurus
    apispec -->|"feeds"| docusaurus

    %% Connections: Application Layer inputs to Build Engine
    react --> docusaurus
    static --> docusaurus
    docusConfig --> docusaurus
    babelConfig --> docusaurus
    packageNode --> docusaurus
    sidebarNode --> docusaurus

    %% Build Process connections
    docusaurus -->|"outputs"| buildProc
    buildProc -->|"triggers"| workflows
    buildProc -->|"triggers"| vercelConfig
    workflows --> vercelHost
    vercelConfig --> vercelHost
    vercelHost -->|"serves"| browser

    %% User interaction with search
    browser -->|"search"| algolia

    %% Styles
    classDef content fill:#a2d2ff,stroke:#333,stroke-width:2px;
    classDef build fill:#ffc8dd,stroke:#333,stroke-width:2px;
    classDef component fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef asset fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef config fill:#fdffb6,stroke:#333,stroke-width:2px;
    classDef external fill:#d0f4de,stroke:#333,stroke-width:2px;
    classDef ci fill:#e2ece9,stroke:#333,stroke-width:2px;
    classDef buildproc fill:#fef9c7,stroke:#333,stroke-width:2px;

    %% Click Events
    click docs "https://github.com/nillionnetwork/nillion-docs/tree/main/docs/"
    click apispec "https://github.com/nillionnetwork/nillion-docs/tree/main/apispec/"
    click react "https://github.com/nillionnetwork/nillion-docs/tree/main/src/"
    click static "https://github.com/nillionnetwork/nillion-docs/tree/main/static/"
    click docusConfig "https://github.com/nillionnetwork/nillion-docs/blob/main/docusaurus.config.js"
    click babelConfig "https://github.com/nillionnetwork/nillion-docs/blob/main/babel.config.js"
    click packageNode "https://github.com/nillionnetwork/nillion-docs/blob/main/package.json"
    click sidebarNode "https://github.com/nillionnetwork/nillion-docs/blob/main/sidebars.js"
    click workflows "https://github.com/nillionnetwork/nillion-docs/tree/main/.github/workflows/"
    click vercelConfig "https://github.com/nillionnetwork/nillion-docs/blob/main/vercel.json"
```
