# shipshapecode/shepherd architecture

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

- Interactive diagram: https://gitdiagram.com/shipshapecode/shepherd
- Repository: https://github.com/shipshapecode/shepherd

## Overview

##### Project type and purpose
- This is a monorepo for an open-source library (Shepherd.js) that provides a digital adoption platform (DAP) core, framework wrappers (React, Ember, Vue, Angular), documentation site, and a marketing landing page. It uses pnpm workspaces to manage multiple packages and sites in one repository.

##### File structure
- Root: configuration (ESLint, Prettier, GitHub Actions), release scripts, workspace definitions (pnpm-workspace.yaml).
- /shepherd.js: the core library source, build (Rollup), Babel config, errors, utils, components, tours.
- /packages/react: React wrapper around Shepherd core, built with Vite, test suite (Vitest/Jest).
- /docs-src: Documentation site built with Astro, guides, API docs, MDX, deployed (Fly.toml).
- /landing: Marketing landing page using Astro, content, images, styles, routing.
- /test: End-to-end (Cypress) and unit tests (Jest) verifying core and wrapper behavior.

##### README for additional insights
- Shepherd core is framework-agnostic and supports multiple frameworks via wrappers.
- There is a commercial license option but this repo is the OSS edition.
- Emphasizes usage, integration points, demos, and contribution guidelines.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Root & CI/CD
    subgraph "Monorepo Root & CI/CD"
        direction TB
        RootConfig["pnpm-workspace.yaml"]:::ci
        PlanRelease["plan-release.yml"]:::ci
        PublishWorkflow["publish.yml"]:::ci
        TestWorkflow["test.yml"]:::ci
        RepoPkg["package.json"]:::ci
    end

    %% Core Package
    subgraph "Core Package (shepherd.js)" 
        direction TB
        CoreDir["shepherd.js/"]:::module
        RollupConfig["rollup.config.mjs"]:::module
        BabelConfig["babel.config.cjs"]:::module
        SrcDir["src/"]:::module
        ShepherdTS["shepherd.ts"]:::module
    end

    %% Adapters
    subgraph "Adapters"
        direction TB
        ReactAdapter["React Wrapper"]:::module
        ReactDir["packages/react/"]:::module
        ReactPkg["package.json"]:::module
        ReactIndex["src/index.tsx"]:::module
        ViteConfig["vite.config.ts"]:::module
        VitestConfig["vitest.config.ts"]:::module
        ReactTestDir["test/"]:::test
    end

    %% Web Apps
    subgraph "Web Apps"
        direction TB
        DocsSite["Docs Site"]:::site
        DocsDir["docs-src/"]:::site
        AstroConfig["astro.config.mjs"]:::site
        FlyToml["fly.toml"]:::site
        DocsContent["src/content/docs/"]:::site

        LandingPage["Landing Page"]:::site
        LandingDir["landing/"]:::site
        LandingAstro["astro.config.mjs"]:::site
        LandingPages["src/pages/"]:::site
    end

    %% Test Suites
    subgraph "Test Suites"
        direction TB
        subgraph "End-to-End Tests" 
            direction TB
            CypressConfig["cypress.config.js"]:::test
            CypressInt["integration/"]:::test
            CypressSup["support/"]:::test
            CypressUtils["utils/"]:::test
        end
        subgraph "Unit Tests"
            direction TB
            JestConfig["jest.config.js"]:::test
            UnitComp["components/"]:::test
            UnitUtils["utils/"]:::test
            StepSpec["step.spec.js"]:::test
        end
    end

    %% External Services
    NpmRegistry["npm Registry"]:::ext
    GitHubActions["GitHub Actions"]:::ext
    FlyHosting["Fly.io Hosting"]:::ext

    %% Relationships
    ReactAdapter -->|"depends on"| CoreDir
    DocsSite -->|"imports core & adapters"| CoreDir
    DocsSite -->|"imports live demos"| ReactAdapter
    LandingPage -->|"links to docs & badges"| DocsSite
    RootConfig -->|uses| ReactAdapter
    RootConfig -->|uses| CoreDir
    PlanRelease -->|triggers build & publish| NpmRegistry
    PublishWorkflow -->|publishes packages| NpmRegistry
    TestWorkflow -->|runs tests| CypressConfig
    TestWorkflow -->|runs tests| JestConfig
    GitHubActions -->|runs workflows| PlanRelease
    GitHubActions -->|runs workflows| PublishWorkflow
    GitHubActions -->|runs workflows| TestWorkflow
    DocsSite -->|deploys to| FlyHosting
    LandingPage -->|deploys to| FlyHosting

    CypressConfig -->|tests| CoreDir
    CypressConfig -->|tests| ReactAdapter
    JestConfig -->|tests| CoreDir
    JestConfig -->|tests| ReactAdapter

    %% Click Events
    click RootConfig "https://github.com/shipshapecode/shepherd/blob/main/.github/workflows/plan-release.yml"
    click PlanRelease "https://github.com/shipshapecode/shepherd/blob/main/.github/workflows/plan-release.yml"
    click PublishWorkflow "https://github.com/shipshapecode/shepherd/blob/main/.github/workflows/publish.yml"
    click TestWorkflow "https://github.com/shipshapecode/shepherd/blob/main/.github/workflows/test.yml"
    click RootConfig "https://github.com/shipshapecode/shepherd/blob/main/pnpm-workspace.yaml"
    click RepoPkg "https://github.com/shipshapecode/shepherd/blob/main/package.json"

    click CoreDir "https://github.com/shipshapecode/shepherd/tree/main/shepherd.js/"
    click RollupConfig "https://github.com/shipshapecode/shepherd/blob/main/shepherd.js/rollup.config.mjs"
    click BabelConfig "https://github.com/shipshapecode/shepherd/blob/main/shepherd.js/babel.config.cjs"
    click SrcDir "https://github.com/shipshapecode/shepherd/tree/main/shepherd.js/src/"
    click ShepherdTS "https://github.com/shipshapecode/shepherd/blob/main/shepherd.js/src/shepherd.ts"

    click ReactDir "https://github.com/shipshapecode/shepherd/tree/main/packages/react/"
    click ReactPkg "https://github.com/shipshapecode/shepherd/blob/main/packages/react/package.json"
    click ReactIndex "https://github.com/shipshapecode/shepherd/blob/main/packages/react/src/index.tsx"
    click ViteConfig "https://github.com/shipshapecode/shepherd/blob/main/packages/react/vite.config.ts"
    click VitestConfig "https://github.com/shipshapecode/shepherd/blob/main/packages/react/vitest.config.ts"
    click ReactTestDir "https://github.com/shipshapecode/shepherd/tree/main/packages/react/test/"

    click DocsDir "https://github.com/shipshapecode/shepherd/tree/main/docs-src/"
    click AstroConfig "https://github.com/shipshapecode/shepherd/blob/main/docs-src/astro.config.mjs"
    click FlyToml "https://github.com/shipshapecode/shepherd/blob/main/docs-src/fly.toml"
    click DocsContent "https://github.com/shipshapecode/shepherd/tree/main/docs-src/src/content/docs/"

    click LandingDir "https://github.com/shipshapecode/shepherd/tree/main/landing/"
    click LandingAstro "https://github.com/shipshapecode/shepherd/blob/main/landing/astro.config.mjs"
    click LandingPages "https://github.com/shipshapecode/shepherd/tree/main/landing/src/pages/"

    click CypressConfig "https://github.com/shipshapecode/shepherd/blob/main/test/cypress/cypress.config.js"
    click CypressInt "https://github.com/shipshapecode/shepherd/tree/main/test/cypress/integration/"
    click CypressSup "https://github.com/shipshapecode/shepherd/tree/main/test/cypress/support/"
    click CypressUtils "https://github.com/shipshapecode/shepherd/tree/main/test/cypress/utils/"

    click JestConfig "https://github.com/shipshapecode/shepherd/blob/main/test/unit/jest.config.js"
    click UnitComp "https://github.com/shipshapecode/shepherd/tree/main/test/unit/components/"
    click UnitUtils "https://github.com/shipshapecode/shepherd/tree/main/test/unit/utils/"
    click StepSpec "https://github.com/shipshapecode/shepherd/blob/main/test/unit/step.spec.js"

    %% Styles
    classDef module fill:#D0E8FF,stroke:#000
    classDef site fill:#D0FFD0,stroke:#000
    classDef ci fill:#FFE8C0,stroke:#000
    classDef test fill:#E0E0E0,stroke:#000
    classDef ext fill:#FFD8D8,stroke:#000
```
