# redocly/redocly-cli architecture

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

- Interactive diagram: https://gitdiagram.com/redocly/redocly-cli
- Repository: https://github.com/redocly/redocly-cli

## Overview

##### Project type and purpose
- This is an open‑source, monorepo CLI tool (“Redocly CLI”) for managing OpenAPI/AsyncAPI/Arazzo specs: linting, bundling, splitting, building docs, running workflow tests (“respect”).
- Key packages:
– packages/cli: the command‑line interface and entry point
– packages/core: the core processing engine (bundle, lint, split, stats, format, resolve)
– packages/respect-core: the “respect” workflow runner (test‑case execution, arazzo flows)

##### File structure
- Top‑level: docs/ (static guides), packages/ (source code), __tests__/ (end‑to‑end tests), scripts/, resources/, Dockerfile, configs (.eslintrc.yml, tsconfig.json, etc.).
- Monorepo uses Lerna‐style packages. Each package has src/ and __tests__/ subfolders.
- commands in CLI map 1:1 to top‑level features (build‑docs, bundle, lint, split, stats, respect, etc.).
- Config loaders from .redocly.yaml or CLI flags feed into core.
- External calls: cli→packages/core→OpenAPI parsers & decorators; cli→packages/respect-core→HTTP calls / HAR logging for API tests; cli→Reunite API (packages/cli/src/reunite/api); telemetry & update checks.

##### README
- Describes CLI usage, Node vs Docker, commands (lint, bundle, build‑docs, respect, split, stats).
- Mentions plugin/config system & extension points (custom rulesets, decorators).
- Notes hosted “Reunite” integration for publishing.

a. Main components:
– CLI Invocation (bin/cli.js)
– Argument Parser & Dispatcher (commander.js in packages/cli)
– Config Loader (.redocly.yaml, environment vars)
– Command Modules:
- Build‑Docs → core.buildDocs → Redoc template engine (handlebars) → HTML output
- Bundle/Lint/Split/Stats → core.bundle, core.lint, core.split, core.stats → JSON/YAML output
- Respect → respect-core modules → workflow runner → API calls / HAR logs → test reports
- Reunite → API client modules → Redocly hosted services
– Core Library (packages/core): parse & traverse OpenAPI/AsyncAPI, apply decorators & rules, bundle and resolve refs, format errors.
– Respect‑Core Library (packages/respect-core): parse arazzo YAML, generate test definitions, run HTTP calls, evaluate success criteria.
– External Dependencies:
- File System (read/write spec files, output docs)
- Network (Reunite API, remote config, HTTP calls for “respect”)
- Docker runtime (optional container)
– CI/CD & Release Scripts (scripts/, .github/workflows)
– Documentation (docs/ served separately)

b. Relationships & interactions:
– User types `redocly [command] [options]` → bin/cli.js → dispatcher
– Dispatcher loads config → invokes relevant command module
– Command module delegates to core or respect-core APIs
– Core reads spec files, applies resolution & linting pipeline → returns AST/results → CLI formats & writes to console or files
– Respect‑Core reads spec + workflows → for each test: makes HTTP calls → matches responses against schemas & criteria → outputs summary
– Some commands call Reunite API client (packages/cli/src/reunite) to push status or docs to Redocly hosted service
– Dockerfile wraps the same CLI, mounting host spec directory

c. Architectural patterns / design principles:
– Monorepo with loosely coupled packages (CLI, Core, Respect)
– Plugin/Decorator pattern for extensibility of rules & transformations
– Single entry point and command dispatcher (Command pattern)
– Pipelines: parsing → resolving refs → applying decorators → linting/bundling → output
– Separation of concerns: CLI/UI vs core logic vs test runner

d. Relevant technologies/frameworks:
– Node.js + TypeScript
– Commander.js (or similar) for CLI
– Handlebars templates for build‑docs
– AJV for JSON schema validation in lint
– Axios / fetch for HTTP calls in respect-core and reunite
– Lerna/Yarn workspaces for monorepo
– Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::actor --> CLI[("CLI Invocation\npackages/cli/bin/cli.js")]:::internal
    click CLI "https://github.com/redocly/redocly-cli/blob/main/packages/cli/bin/cli.js"
    CLI --> Dispatcher[("Argument Parser & Dispatcher\npackages/cli/src/index.ts")]:::internal
    click Dispatcher "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/index.ts"
    Dispatcher --> ConfigLoader[("Config Loader\npackages/core/src/config/load.ts")]:::internal
    click ConfigLoader "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/config/load.ts"

    subgraph "CLI Commands" 
        BuildDocs["Build‑Docs Cmd"]:::internal
        click BuildDocs "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/commands/build-docs/index.ts"
        BundleCmd["Bundle Cmd"]:::internal
        click BundleCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/commands/bundle.ts"
        LintCmd["Lint Cmd"]:::internal
        click LintCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/commands/lint.ts"
        SplitCmd["Split Cmd"]:::internal
        click SplitCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/commands/split/index.ts"
        StatsCmd["Stats Cmd"]:::internal
        click StatsCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/commands/stats.ts"
        RespectCmd["Respect Cmd"]:::internal
        PushCmd["Push"]:::internal
        click PushCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/reunite/commands/push.ts"
        PushStatusCmd["Push‑Status"]:::internal
        click PushStatusCmd "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/reunite/commands/push-status.ts"
    end

    Dispatcher --> BuildDocs
    Dispatcher --> BundleCmd
    Dispatcher --> LintCmd
    Dispatcher --> SplitCmd
    Dispatcher --> StatsCmd
    Dispatcher --> RespectCmd
    Dispatcher --> PushCmd
    Dispatcher --> PushStatusCmd

    subgraph "Core Library" 
        CoreIndex["Core API\npackages/core/src/index.ts"]:::internal
        click CoreIndex "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/index.ts"
        BundleAPI["Bundle API\npackages/core/src/bundle.ts"]:::pipeline
        click BundleAPI "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/bundle.ts"
        LintAPI["Lint API\npackages/core/src/lint.ts"]:::pipeline
        click LintAPI "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/lint.ts"
        ResolveAPI["Resolve API\npackages/core/src/resolve.ts"]:::pipeline
        click ResolveAPI "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/resolve.ts"
        StatsAPI["Stats API\npackages/core/src/rules/other/stats.ts"]:::pipeline
        click StatsAPI "https://github.com/redocly/redocly-cli/blob/main/packages/core/src/rules/other/stats.ts"
    end

    BuildDocs --> CoreIndex
    BundleCmd --> BundleAPI
    LintCmd --> LintAPI
    SplitCmd --> ResolveAPI
    StatsCmd --> StatsAPI

    subgraph "Respect Core Library"
        RespectIndex["Respect‑Core API\npackages/respect-core/src/index.ts"]:::internal
        click RespectIndex "https://github.com/redocly/redocly-cli/blob/main/packages/respect-core/src/index.ts"
        Handlers["Respect Handlers\npackages/respect-core/src/handlers/index.ts"]:::pipeline
        click Handlers "https://github.com/redocly/redocly-cli/blob/main/packages/respect-core/src/handlers/index.ts"
        FlowRunner["Flow Runner\npackages/respect-core/src/modules/flow-runner/index.ts"]:::pipeline
        click FlowRunner "https://github.com/redocly/redocly-cli/blob/main/packages/respect-core/src/modules/flow-runner/index.ts"
        DescGen["Description Generator\npackages/respect-core/src/modules/arazzo-description-generator/index.ts"]:::pipeline
        click DescGen "https://github.com/redocly/redocly-cli/blob/main/packages/respect-core/src/modules/arazzo-description-generator/index.ts"
        CLIFormatter["CLI Output Formatter\npackages/respect-core/src/modules/cli-output/index.ts"]:::pipeline
        click CLIFormatter "https://github.com/redocly/redocly-cli/blob/main/packages/respect-core/src/modules/cli-output/index.ts"
    end

    RespectCmd --> RespectIndex
    RespectIndex --> Handlers --> FlowRunner --> DescGen --> CLIFormatter

    PushCmd --> APIClient[("Reunite API Client\npackages/cli/src/reunite/api/api-client.ts")]:::internal
    click APIClient "https://github.com/redocly/redocly-cli/blob/main/packages/cli/src/reunite/api/api-client.ts"
    PushStatusCmd --> APIClient

    CoreIndex -->|"read/write specs"| FileSystem[("File System")]:::external
    BuildDocs -->|"template render"| Handlebars[("Handlebars Engine")]:::external
    RespectIndex -->|"HTTP calls/HAR logging"| Network[("Network Services")]:::external
    APIClient -->|"push status/docs"| Network
    Docker[("Docker Engine\nDockerfile")]:::external
    click Docker "https://github.com/redocly/redocly-cli/tree/main/Dockerfile"
    User -->|"docker run"| Docker

    classDef internal fill:#a8d5a2,stroke:#048a06,color:#000
    classDef pipeline fill:#ffa347,stroke:#c95c00,color:#000
    classDef external fill:#a3c4f3,stroke:#1a4a8a,color:#000
    classDef actor fill:#ffffff,stroke:#333333,color:#000,stroke-width:2px

    class User actor
    class FileSystem,Network,Handlebars,Docker external
```
