# shopware/developer-portal architecture

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

- Interactive diagram: https://gitdiagram.com/shopware/developer-portal
- Repository: https://github.com/shopware/developer-portal

## Overview

##### Project type and purpose
- This is an open-source static documentation portal (“Developer Portal”) built on top of a Vitepress template.
- It bundles a custom CLI (`docs-cli.cjs`) to embed and manage content from multiple Shopware sub-repositories, indexes search with Algolia, and orchestrates builds/tests/deployments via GitHub Actions.

##### File structure
- Top-level directories:
- `.github/` – CI/CD workflows and custom GitHub Actions.
- `.devcontainer/`, `gitpod/` – dev-environment definitions (Docker, VSCode, Gitpod).
- `.vitepress/` – site configuration, theme extensions, navigation.
- `src/` – markdown content, Vue components, and embedded docs mounts.
- `.algolia/` – scripts and config to crawl and index site content.
- `cli/` – placeholder for custom CLI (here a single `docs-cli.cjs` at root).
- `__tests__/` – end-to-end tests (Playwright + Vitest).
- `storybook/` – component previews.
- config files: `package.json`, `tsconfig.json`, `vercel.json`.

##### Extract insights from the README
- Core responsibilities:
- “Shopware Docs CLI” embeds content from external repos into the portal under `src/`.
- Vitepress-based front end provided by an external template package.
- Single deployment domain via GitHub Actions.

##### Main components
a. Developer Portal GitHub Repository
b. Shopware Docs CLI
c. External Documentation Repositories
- shopware/docs
- shopware/frontends
- shopware/meteor
- shopware/release-notes
- shopware/store-api-reference
- shopware/admin-api-reference
d. Vitepress Site Engine & Theme (external NPM package)
e. Frontend Vue Components & Markdown Content (`src/` and embedded mount points)
f. Search Indexer (Algolia crawler scripts + config)
g. Storybook Component Preview Environment
h. Testing Frameworks & Suites
- E2E tests (Playwright + Vitest)
- Unit/mocks for Vitepress
i. Dev Environments
- Docker DevContainer, Gitpod
j. CI/CD Pipeline (GitHub Actions workflows)
k. Hosting/Deployment Target (Vercel or static host on `developer.shopware.com`)

##### Relationships and interactions
- Docs CLI → pulls content from External Repos → writes to `src/<mount-point>/`
- Vitepress Engine + Theme + `src/` → generates static site build
- Algolia crawler scripts read built site files → push search index to Algolia
- Storybook reads Vue components in `src/components/` → serves component library preview
- CI/CD (GitHub Actions) sequences:
1. Checkout code
2. Install dependencies
3. Run Docs CLI embed step
4. Build site with Vitepress
5. Run tests (E2E + Unit)
6. Crawl and update Algolia index
7. Deploy to hosting target
- DevContainer/Gitpod provide reproducible local dev environment for above steps.

##### Architectural patterns & design principles
- Modular embedding: content is not hard-coded but dynamically pulled from multiple repos.
- Separation of concerns: CLI embedding, site generation, indexing, testing, and deployment are distinct stages.
- Reusability/Extensibility: Vitepress template and CLI can be used by other teams/projects.
- Infrastructure as code: dev-containers, GitHub Actions, and scripts define environments & pipelines declaratively.

##### Relevant technologies, frameworks, libraries
- Node.js & npm/pnpm
- Vitepress (static site generator based on Vite + Vue)
- Vue 3 (Vue components for custom UI)
- Shopware Docs CLI (custom JavaScript script)
- Playwright + Vitest (E2E & unit tests)
- Storybook (UI component explorer)
- Algolia (search indexing)
- Docker (DevContainer, Gitpod environments)
- GitHub Actions (CI/CD)
- Vercel (or any static host for final deployment)

- Use clear labels for each of the components listed in step 4.
- “CLI → Embedded Content”
- “Repo + CLI → Build Process”
- “Build Output → Algolia”
- “Build Output → Deploy Target”
- Source & embedding
- Build & test
- Indexing & deployment

##### Detail
- Sub-repository integration as its own node under “External Docs.”
- GitHub Actions workflows that orchestrate each stage.
- Feedback loops (e.g., test failures trigger PR checks).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source & Embedding
    subgraph "Source & Embedding"
        direction TB
        DevRepo["Developer Portal GitHub Repository"]:::code
        CLI["Shopware Docs CLI"]:::code
        subgraph "External Documentation Repositories"
            direction TB
            ExtAdmin["shopware/admin-api-reference"]:::code
            ExtStore["shopware/store-api-reference"]:::code
            ExtFront["shopware/frontends"]:::code
            ExtMeteor["shopware/meteor"]:::code
            ExtRelease["shopware/release-notes"]:::code
            ExtStoreAPI["shopware/store-api-reference"]:::code
        end
    end

    %% Build & Test
    subgraph "Build & Test"
        direction TB
        Vitepress["Vitepress Site Engine & Theme"]:::code
        Src["Frontend Vue Components & Markdown Content"]:::code
        Build["Static Site Build"]:::env
        Storybook["Storybook Component Preview"]:::env
        Tests["Testing Frameworks & Suites"]:::test
    end

    %% Indexing & Deployment
    subgraph "Indexing & Deployment"
        direction TB
        Algolia["Search Indexer (Algolia)"]:::ext
        CI["CI/CD Pipeline (GitHub Actions)"]:::env
        Deploy["Hosting/Deployment Target (Vercel)"]:::ext
    end

    %% Dev Environments
    subgraph "Dev Environments"
        direction TB
        DevContainer["Docker DevContainer & Gitpod"]:::env
    end

    %% Relationships
    DevRepo --> CLI
    CLI -->|"embeds content into"| Src
    ExtAdmin --> Src
    ExtStore --> Src
    ExtFront --> Src
    ExtMeteor --> Src
    ExtRelease --> Src
    ExtStoreAPI --> Src

    Vitepress --> Build
    Src --> Build
    Build --> Storybook
    Build --> Tests

    Build --> Algolia
    Build --> Deploy
    CI --> Build
    CI --> Tests
    CI --> Algolia
    CI --> Deploy

    DevContainer --> DevRepo
    DevContainer --> CLI

    %% Click Events
    click DevRepo "https://github.com/shopware/developer-portal/tree/main//"
    click CLI "https://github.com/shopware/developer-portal/blob/main/docs-cli.cjs"
    click CLI "https://github.com/shopware/developer-portal/tree/main/cli/"
    click CLI "https://github.com/shopware/developer-portal/blob/main/.github/scripts/embed.sh"
    click ExtAdmin "https://github.com/shopware/developer-portal/blob/main/src/resources/api/admin-api-reference.md"
    click ExtStore "https://github.com/shopware/developer-portal/blob/main/src/resources/api/store-api-reference.md"
    click ExtFront "https://github.com/shopware/developer-portal/blob/main/src/storefront/index.md"
    click Vitepress "https://github.com/shopware/developer-portal/blob/main/.vitepress/config.ts"
    click Src "https://github.com/shopware/developer-portal/blob/main/src/components/SwagAlgoliaSearchPage.vue"
    click Src "https://github.com/shopware/developer-portal/blob/main/src/components/SwagCardExtend.vue"
    click Algolia "https://github.com/shopware/developer-portal/blob/main/.algolia/config.json"
    click Algolia "https://github.com/shopware/developer-portal/blob/main/.algolia/crawl.sh"
    click Algolia "https://github.com/shopware/developer-portal/blob/main/.github/workflows/algolia-crawl.yml"
    click Storybook "https://github.com/shopware/developer-portal/blob/main/.storybook/main.ts"
    click Tests "https://github.com/shopware/developer-portal/blob/main/__tests__/e2e/playwright.config.ts"
    click DevContainer "https://github.com/shopware/developer-portal/blob/main/.devcontainer/devcontainer.json"
    click CI "https://github.com/shopware/developer-portal/blob/main/.github/workflows/checkout-test-build-deploy.yml"
    click Deploy "https://github.com/shopware/developer-portal/blob/main/vercel.json"

    %% Styles
    classDef code fill:#bbf,stroke:#333,stroke-width:1px
    classDef ext fill:#bfb,stroke:#333,stroke-width:1px
    classDef env fill:#fbb,stroke:#333,stroke-width:1px
    classDef test fill:#fbf,stroke:#333,stroke-width:1px
```
