# storyblok/monoblok architecture

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

- Interactive diagram: https://gitdiagram.com/storyblok/monoblok
- Repository: https://github.com/storyblok/monoblok

## Overview

##### Project Type and Purpose
- This is a Node.js-based monorepo (“Monoblok”) that centralizes all Storyblok open-source SDKs, framework integrations, utilities, and CLI tools.
- It uses PNPM workspaces for package management and NX for build orchestration, caching, and dependency visualization.
- The repo includes: core SDKs (@storyblok/js, @storyblok/js-client), framework adapters (@storyblok/react, vue, nuxt, svelte, astro), a richtext renderer, and the storyblok-cli.

##### Key Architectural Components
a. Root Workspace
- pnpm-workspace.yaml: defines which folders are part of the workspace.
- nx.json: configures NX tasks, caching, dependency graph.
- GitHub Actions (.github/workflows): CI/CD pipelines for build, test, publish.
- Husky & lint-staged: pre-commit/commit-msg hooks.
b. Package Modules (packages/*)
- Each package folder (js, js-client, react, vue, nuxt, svelte, astro, richtext, cli) is an isolated npm module.
- Source code (src/), tests (tests/ or __tests__), playground demos.
- Each has its own package.json, build/test scripts.
c. CLI Tool (packages/cli)
- Exposes command-line interface for Storyblok projects.
- Has its own build flow, internal commands, API calls to Storyblok services.
d. Development & Build Orchestrator
- NX: defines targets (build, test, lint, graph), computes affected packages, parallel execution, caching.
- monoblock-cli (tools/monoblok): admin helper for repo maintenance and migrations.
e. CI/CD
- GitHub Actions workflows triggered on push/PR: run pnpm install, pnpm nx affected:test/build, lint, then publish to npm.
- commitlint, release-it, publishing pipelines.

##### Relationships and Data Flow
- Developer Machine → pnpm install (root) → workspace packages are linked.
- Developer issues pnpm build/test via NX → NX resolves inter-package dependencies, runs tasks in correct order.
- monoblock-cli (tooling) ↔ repo for maintenance scripts.
- GitHub Actions → checks code, runs NX targets, on success publishes updated packages to npm registry.
- SDK packages → call out to external Storyblok Content Delivery API at runtime.

##### Architectural Patterns and Principles
- Monorepo with polytonic package grouping by functionality.
- Modular design: each SDK / integration is a standalone module.
- Shared development config (ESLint, TypeScript, Vitest, Cypress) at root and overridden per package.
- CI/CD as code: workflows defined in .github.
- Dependency graph visualization and incremental builds using NX.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Root Tooling Layer
    subgraph "Root Tooling" 
        direction TB
        PNPMWS["pnpm-workspace.yaml"]:::rootTooling
        LOCK["pnpm-lock.yaml"]:::rootTooling
        NXCfg["nx.json"]:::orchestrator
        Husky["Husky & lint-staged"]:::rootTooling
        GHActions["GitHub Actions CI/CD"]:::rootTooling
        ReleaseCfg["Lint & Release Config"]:::rootTooling
    end

    %% Package Modules Layer
    subgraph "Package Modules"
        direction TB
        subgraph "Core SDKs"
            direction TB
            JS["@storyblok/js"]:::core
            JSClient["@storyblok/js-client"]:::core
        end
        subgraph "Framework Integrations"
            direction TB
            React["@storyblok/react"]:::framework
            Vue["@storyblok/vue"]:::framework
            Nuxt["@storyblok/nuxt"]:::framework
            Svelte["@storyblok/svelte"]:::framework
            Astro["@storyblok/astro"]:::framework
        end
        subgraph "Utilities & CLI"
            direction TB
            Richtext["@storyblok/richtext"]:::util
            CLI["storyblok-cli"]:::cli
        end
    end

    %% Tooling Layer
    MonoblokCLI["monoblok-cli (tools/monoblok)"]:::cli

    %% External Services
    NPMReg[(npm Registry)]:::external
    StoryblokAPI[(Storyblok Content Delivery API)]:::external

    %% Developer
    Developer["Developer Machine"]:::external

    %% Orchestrator Node
    NX["NX Orchestrator"]:::orchestrator

    %% Connections
    Developer -->|"pnpm install"| PNPMWS
    Developer -->|"pnpm install"| LOCK
    Developer -->|"nx build/test"| NX
    Developer -->|"run monoblock-cli"| MonoblokCLI

    PNPMWS -->|links packages| JS
    PNPMWS -->|links packages| JSClient
    PNPMWS -->|links packages| React
    PNPMWS -->|links packages| Vue
    PNPMWS -->|links packages| Nuxt
    PNPMWS -->|links packages| Svelte
    PNPMWS -->|links packages| Astro
    PNPMWS -->|links packages| Richtext
    PNPMWS -->|links packages| CLI

    NX -->|"build/test tasks"| JS
    NX -->|"build/test tasks"| JSClient
    NX -->|"build/test tasks"| React
    NX -->|"build/test tasks"| Vue
    NX -->|"build/test tasks"| Nuxt
    NX -->|"build/test tasks"| Svelte
    NX -->|"build/test tasks"| Astro
    NX -->|"build/test tasks"| Richtext
    NX -->|"build/test tasks"| CLI

    GHActions -->|runs| PNPMWS
    GHActions -->|runs| NX
    GHActions -->|triggers publish| NPMReg

    JS -->|runtime fetch| StoryblokAPI
    JSClient -->|runtime fetch| StoryblokAPI
    React -->|runtime fetch| StoryblokAPI
    Vue -->|runtime fetch| StoryblokAPI
    Nuxt -->|runtime fetch| StoryblokAPI
    Svelte -->|runtime fetch| StoryblokAPI
    Astro -->|runtime fetch| StoryblokAPI
    Richtext -->|uses| StoryblokAPI
    CLI -->|uses| StoryblokAPI

    MonoblokCLI -->|maintains| PNPMWS
    MonoblokCLI -->|updates| NXCfg

    %% Click Events
    click PNPMWS "https://github.com/storyblok/monoblok/blob/main/pnpm-workspace.yaml"
    click LOCK "https://github.com/storyblok/monoblok/blob/main/pnpm-lock.yaml"
    click NXCfg "https://github.com/storyblok/monoblok/blob/main/nx.json"
    click Husky "https://github.com/storyblok/monoblok/tree/main/.husky/pre-commit"
    click Husky "https://github.com/storyblok/monoblok/tree/main/.husky/commit-msg"
    click Husky "https://github.com/storyblok/monoblok/blob/main/lint-staged.config.js"
    click Husky "https://github.com/storyblok/monoblok/blob/main/commitlint.config.js"
    click GHActions "https://github.com/storyblok/monoblok/blob/main/.github/workflows/ci.yaml"
    click GHActions "https://github.com/storyblok/monoblok/blob/main/.github/workflows/commitlint.yaml"
    click GHActions "https://github.com/storyblok/monoblok/blob/main/.github/workflows/pr-preview.yaml"
    click GHActions "https://github.com/storyblok/monoblok/blob/main/.github/workflows/publish.yaml"
    click JS "https://github.com/storyblok/monoblok/blob/main/packages/js/src/index.ts"
    click JSClient "https://github.com/storyblok/monoblok/blob/main/packages/js-client/src/index.ts"
    click React "https://github.com/storyblok/monoblok/blob/main/packages/react/src/index.ts"
    click Vue "https://github.com/storyblok/monoblok/blob/main/packages/vue/src/index.ts"
    click Nuxt "https://github.com/storyblok/monoblok/blob/main/packages/nuxt/src/module.ts"
    click Svelte "https://github.com/storyblok/monoblok/blob/main/packages/svelte/src/lib/index.ts"
    click Astro "https://github.com/storyblok/monoblok/blob/main/packages/astro/src/index.ts"
    click Richtext "https://github.com/storyblok/monoblok/blob/main/packages/richtext/src/richtext.ts"
    click CLI "https://github.com/storyblok/monoblok/blob/main/packages/cli/src/index.ts"
    click MonoblokCLI "https://github.com/storyblok/monoblok/blob/main/tools/monoblok/src/index.ts"

    %% Styles
    classDef rootTooling fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef framework fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef util fill:#ffecb3,stroke:#333,stroke-width:1px
    classDef cli fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#e1bee7,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
