# shopware/docs architecture

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

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

## Overview

##### Project Type and Purpose
- This repository holds the developer documentation for Shopware 6. It organizes “Concepts”, “Guides”, “Products”, and “Resources” into clearly defined sections.
- Its primary function is to provide a central location where developers can access high-quality, maintained documentation about Shopware concepts and integration details.
- The README and file structure emphasize automation (through GitHub workflows) for content validation and build processes before deployment.

##### Analyzing the File Structure
- Key top-level folders include:
- “concepts” – containing theory and API explanations
- “guides” – step-by-step instructions related to hosting, installation, and integrations
- “products” – documentation on various Shopware products and extensions (CLI commands, digital sales rooms, etc.)
- “resources” – guidelines, references for code, testing, and configuration details
- “.github/workflows” – YAML files for automating checks such as markdown style, spellcheck, grammar, external links, file formatting, and updating ADRs.
- There are also multiple scripts under “.github/scripts”, which are used for migrations, formatting rules, updating ADRs, etc.
- Configuration files (like .editorconfig, .gitignore, and others) indicate standard practices to ensure consistency in developer contributions.

##### Main Components
a. Documentation Content Modules:
- “Concepts”, “Guides”, “Products”, “Resources” folders (each representing a major content module).
- “Assets” – containing images, ADR files, and other media that support the documents.
b. CI/CD & Automation Workflows:
- GitHub Actions Workflows (e.g., file-format-check, markdown-style-check, spellcheck, external link check).
- Scripts in “.github/scripts” that help keep certain files in sync with the Shopware core repository.
- These workflows are triggered by events (push, pull_request, schedule) to validate and deploy the documentation.
c. Version Control & Repository:
- The repository itself (hosted on GitHub) is the source for the documentation and workflow definitions.
d. External Dependencies and Tooling:
- Tools such as Reviewdog (for grammar/language check), markdown-lint, py-spelling, and lychee are integrated into the CI pipelines.
- There is also reference to deployment mechanisms (via GitHub Pages or a similar hosting mechanism pointing to developer.shopware.com).

##### Relationships and Interactions
- The content (markdown files and assets) is stored and maintained in the repository.
- GitHub Action workflows continuously test and build the repository whenever changes occur.
- The workflows perform “Linting”, “Spellchecking”, “Link Validation”, etc.
- Once validated, the documentation is deployed (or updated) on the developer portal (https://developer.shopware.com/docs).
- Synchronization scripts keep selected parts (e.g., ADRs, code guidelines) in sync with the main Shopware repository.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different folders for documentation content vs. CI/CD & automation.
- Continuous Integration: Automated workflows ensure quality and correctness before changes are merged.
- Modularity: The documentation itself is modularized into distinct sections (Concepts, Guides, Products, Resources) to support ease of navigation and contribution.
- Extensibility: Numerous guides and reference documents indicate that the system is built for extensibility and collaboration via community contributions.

- Branch it to show the major categories of documentation content (“Concepts”, “Guides”, “Products”, “Resources”, “Assets”).
- CI/CD branch to the “Deployment Server/Developer Portal” that hosts developer.shopware.com.
- Clearly label synchronization flows (e.g., from our “Shopware Core ADR” nodes to the documentation ADR folder) as well as feedback loops (like failure notifications if a workflow fails).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developers"]:::external
    Repo["Source Repository (GitHub)"]:::repo

    subgraph "Documentation Content Modules"
        Concepts["Concepts (Markdown)"]:::documentation
        Guides["Guides (Markdown)"]:::documentation
        Products["Products (Markdown)"]:::documentation
        Resources["Resources (Markdown)"]:::documentation
        Assets["Assets (Images/ADR)"]:::documentation
    end

    subgraph "CI/CD & Automation"
        GHWorkflows["GitHub Actions Workflows"]:::cicd
        AutomationScripts["Automation Scripts"]:::cicd
        Tools["External Tools (Reviewdog,markdown-lint,etc.)"]:::cicd
    end

    Deployment["Deployment Server/Developer Portal (developer.shopware.com/docs)"]:::external
    CoreRepo["Shopware Core Repository (Sync)"]:::external

    Developer -->|"content_update"| Repo
    Repo -->|"stores"| Concepts
    Repo -->|"stores"| Guides
    Repo -->|"stores"| Products
    Repo -->|"stores"| Resources
    Repo -->|"stores"| Assets

    Repo -->|"triggers"| GHWorkflows
    GHWorkflows -->|"executes"| AutomationScripts
    AutomationScripts -->|"invokes"| Tools
    GHWorkflows -->|"validates_and_builds"| Deployment
    AutomationScripts -->|"syncs_with"| CoreRepo

    %% Click Events
    click Concepts "https://github.com/shopware/docs/tree/main/concepts/"
    click Guides "https://github.com/shopware/docs/tree/main/guides/"
    click Products "https://github.com/shopware/docs/tree/main/products/"
    click Resources "https://github.com/shopware/docs/tree/main/resources/"
    click Assets "https://github.com/shopware/docs/tree/main/assets/"
    click GHWorkflows "https://github.com/shopware/docs/tree/main/.github/workflows/"
    click AutomationScripts "https://github.com/shopware/docs/tree/main/.github/scripts/"
    click Repo "https://github.com/shopware/docs/tree/main/./"

    %% Styles
    classDef documentation fill:#A7DDF2, stroke:#005580, stroke-width:2px;
    classDef cicd fill:#C3E2A1, stroke:#558B2F, stroke-width:2px;
    classDef external fill:#FDE2A7, stroke:#A15F00, stroke-width:2px;
    classDef repo fill:#D3D3D3, stroke:#696969, stroke-width:2px;
```
