# jungvonmatt/storyblok-migrations architecture

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

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

## Overview

##### Project type and purpose
- Type: Command-line application built with Node.js & TypeScript.
- Purpose: Extend Storyblok’s CLI by providing schema and content migrations with full TypeScript support, along with configuration management, code generation, and rollback capabilities.

##### File structure
- bin/cli.ts – Entry point of the CLI (Commander.js).
- src/commands – CLI subcommands (config, login, pull-components, generate-types, generate-migration, run).
- src/handlers – Business logic per command broken into sub-folders (component, componentGroup, datasource, story, transformEntries).
- src/utils – Shared utilities (API wrappers, config loader, migration runner, schema helpers, Storyblok API integration).
- src/templates – Prebuilt templates for new migrations.
- src/types – TypeScript interfaces and type definitions.
- migrations folder (implicit) – Generated migration scripts.
- Configuration files: .storyblokrc.json, .env, tsconfig.json.
- External integrations: Storyblok CLI, Storyblok REST API.

##### Extract architectural insights from README
- Layers: CLI layer → Command parsing → Handlers → Utils → External API/CLI → Filesystem.
- Key technologies: Commander.js (CLI), Inquirer.js (prompts), Cosmiconfig (config), Jiti (ESM loader), Storyblok CLI & API.

##### Main components and their interactions
a. User & Shell
– User invokes `sb-migrate` commands in terminal.
b. CLI Frontend (bin/cli.ts)
– Parses arguments via Commander.js, triggers appropriate command.
c. Commands Layer (src/commands)
– Defines command metadata and maps commands to handler functions.
d. Handlers Layer (src/handlers)
– Implements core use cases:
- config: prompts, loads/saves `.storyblokrc.json`
- login: delegates to Storyblok CLI
- pull-components: uses Storyblok CLI & API, writes component schemas JSON
- generate-types: reads schemas, emits TypeScript definitions
- generate-migration: copies template into `migrations/…` with timestamp
- run: loads migration file, calls migration runner (utils/migration), interacts with Storyblok API
e. Utility Layer (src/utils)
– API wrappers, config loader, migration engine, schema helpers, file I/O.
f. Templates (src/templates)
– Source code templates for each migration type.
g. File System
– Config file (`.storyblokrc.json` or `.env`), schema JSON, generated types, migrations folder, template source.
h. External Services
– Storyblok CLI (shell tool), Storyblok REST API (HTTP requests).
i. Testing & CI
– Vitest tests in src/__tests__, GitHub Actions workflows.

##### Architectural patterns & principles
- Layered architecture: separation between CLI parsing, command definition, business handlers, utility services.
- Template-based code generation for consistency.
- Type-safe boundaries: TypeScript interfaces in src/types and generated code.
- Modular design: handlers and utils are isolated per feature.
- External adapter pattern: clear boundary between internal logic and Storyblok CLI/API integrations.

– Top: “User & Shell”
– Next: “CLI Frontend (bin/cli.ts)”
– Middle: “Commands → Handlers → Utils”
– Bottom: “Filesystem” & “External Services”
2. Within the “Commands → Handlers → Utils” cluster:
3. At the bottom:
- read/write config, templates → Filesystem
- spawn Storyblok CLI → External Services
- HTTP calls → Storyblok API
4. Testing & CI can be shown as a side-module: tests trigger src/__tests__, run via Vitest in GitHub Actions.

##### Diagramming conventions
- CLI/Parser (orange)
- Commands/Handlers (blue)
- Utilities (green)
- Filesystem (gray)
- External Services (purple)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top layer: User & Shell
    subgraph "User & Shell"
        U["User & Shell"]:::external
    end

    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI["CLI Frontend (bin/cli.ts)"]:::cli
    end

    %% Commands Layer
    subgraph "Commands Layer"
        ConfigC["Command: config"]:::command
        LoginC["Command: login"]:::command
        PullC["Command: pull-components"]:::command
        GenTypesC["Command: generate-types"]:::command
        GenMigC["Command: generate-migration"]:::command
        RunC["Command: run"]:::command
    end

    %% Handlers Layer
    subgraph "Handlers Layer"
        HI["Handlers Index"]:::handler
        ComponentH["Component Handlers"]:::handler
        GroupH["ComponentGroup Handlers"]:::handler
        DS_H["DataSource Handlers"]:::handler
        StoryH["Story Handlers"]:::handler
        TransformH["TransformEntries Handler"]:::handler
    end

    %% Utility Layer
    subgraph "Utility Layer"
        API["Storyblok API Wrapper"]:::util
        CLIAdapter["Storyblok CLI Adapter"]:::util
        ConfigU["Configuration Loader"]:::util
        MigEngine["Migration Engine"]:::util
        SchemaU["Schema Component Helpers"]:::util
        CompU["Component Utility Helpers"]:::util
    end

    %% Templates
    subgraph "Templates"
        Templates["Templates"]:::templates
    end

    %% Filesystem & External Services
    subgraph "Infrastructure"
        FS["Filesystem"]:::fs
        SBCLI["Storyblok CLI"]:::external
        SBAPI["Storyblok REST API"]:::external
    end

    %% Testing & CI
    subgraph "Testing & CI"
        Tests["src/__tests__"]:::test
        Vitest["vitest.config.ts"]:::test
        CI[".github/workflows"]:::test
    end

    %% Connections
    U -->|invokes| CLI
    CLI -->|parses commands| ConfigC
    CLI -->|parses commands| LoginC
    CLI -->|parses commands| PullC
    CLI -->|parses commands| GenTypesC
    CLI -->|parses commands| GenMigC
    CLI -->|parses commands| RunC

    ConfigC -->|"config"| HI
    LoginC -->|"login"| HI
    PullC -->|"pull-components"| HI
    GenTypesC -->|"generate-types"| HI
    GenMigC -->|"generate-migration"| HI
    RunC -->|"run"| HI

    HI --> ComponentH
    HI --> GroupH
    HI --> DS_H
    HI --> StoryH
    HI --> TransformH

    ComponentH -->|uses| API
    ComponentH -->|uses| ConfigU
    ComponentH -->|writes| FS

    GroupH -->|uses| API
    GroupH -->|uses| ConfigU
    GroupH -->|writes| FS

    DS_H -->|uses| API
    DS_H -->|uses| ConfigU
    DS_H -->|writes| FS

    StoryH -->|uses| API
    StoryH -->|uses| ConfigU
    StoryH -->|writes| FS

    TransformH -->|uses| API
    TransformH -->|uses| ConfigU
    TransformH -->|writes| FS

    GenMigC -->|templates| Templates
    Templates -->|files| FS

    ConfigC -->|config load| ConfigU
    RunC -->|migration| MigEngine
    MigEngine -->|HTTP calls| SBAPI

    PullC -->|spawn| SBCLI
    PullC -->|fetch schema| API
    API -->|data| FS

    Tests -->|run tests| Vitest
    CI -->|executes| Vitest

    %% Click Events
    click CLI "https://github.com/jungvonmatt/storyblok-migrations/blob/main/bin/cli.ts"
    click ConfigC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/config.ts"
    click LoginC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/login.ts"
    click PullC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/pull-components.ts"
    click GenTypesC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/generate-types.ts"
    click GenMigC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/generate-migration.ts"
    click RunC "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/commands/run.ts"
    click HI "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/handlers/index.ts"
    click ComponentH "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/handlers/component"
    click GroupH "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/handlers/componentGroup"
    click DS_H "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/handlers/datasource"
    click StoryH "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/handlers/story"
    click TransformH "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/handlers/transformEntries.ts"
    click API "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/api.ts"
    click CLIAdapter "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/storyblok.ts"
    click ConfigU "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/config.ts"
    click MigEngine "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/migration.ts"
    click SchemaU "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/schemaComponentHelpers.ts"
    click CompU "https://github.com/jungvonmatt/storyblok-migrations/blob/main/src/utils/component.ts"
    click Templates "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/templates"
    click Tests "https://github.com/jungvonmatt/storyblok-migrations/tree/main/src/__tests__"
    click Vitest "https://github.com/jungvonmatt/storyblok-migrations/blob/main/vitest.config.ts"
    click CI "https://github.com/jungvonmatt/storyblok-migrations/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,stroke-width:1px
    classDef command fill:#00BFFF,stroke:#333,stroke-width:1px
    classDef handler fill:#1E90FF,stroke:#333,stroke-width:1px
    classDef util fill:#32CD32,stroke:#333,stroke-width:1px
    classDef templates fill:#FFD700,stroke:#333,stroke-width:1px
    classDef fs fill:#A9A9A9,stroke:#333,stroke-width:1px
    classDef external fill:#9370DB,stroke:#333,stroke-width:1px
    classDef test fill:#8B4513,stroke:#333,stroke-width:1px
```
