# rtcamp/snapwp architecture

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

- Interactive diagram: https://gitdiagram.com/rtcamp/snapwp
- Repository: https://github.com/rtcamp/snapwp

## Overview

##### Main Components
- Core Functionality:
- @snapwp/core (located in packages/core): Contains core utilities, configuration management, logging, error handling, and other fundamental functions.
- Next.js Integration:
- @snapwp/next (located in packages/next): Provides the integration layer for Next.js, offering middleware, React components (like custom Link, Image, Error handling, and template renderers), and custom configuration for SnapWP.
- Block Management:
- @snapwp/blocks (located in packages/blocks): Manages the rendering of WordPress blocks. It includes block definitions, default and custom block components for handling various core blocks (e.g., audio, button, gallery, etc.) plus test suites.
- Query/GraphQL Handling:
- @snapwp/query (located in packages/query): Centralizes WPGraphQL query handling, providing fragments, queries, and query engine functionality for fetching data from WordPress.
- Developer Tooling:
- CLI: @snapwp/cli for bootstrapping applications (found in packages/cli).
- Codegen & Linting Configurations: Packages such as @snapwp/codegen-config, @snapwp/eslint-config, and @snapwp/prettier-config.
- External WordPress Plugin:
- The SnapWP Helper plugin (referenced in the README) that enhances WordPress and WPGraphQL on the CMS side.
- Examples & Documentation:
- Provided examples (like the Next.js starter app in examples/nextjs) serve as practical implementations to illustrate integration.
- Infrastructure & Configuration:
- Various configuration files (in config, .env.example, GitHub workflows, etc.) indicate automated builds, test setups, and deployment pipelines.

##### Their Relationships and Interactions
- The “Core” package provides foundational services that are consumed by the other packages.
- The Next.js integration layer uses both the Core and Blocks packages to assemble the frontend application.
- The Blocks package renders WordPress block data by interfacing with the Query package, which in turn communicates with WPGraphQL.
- The CLI & developer tooling packages (CLI, codegen, eslint, prettier) support application setup, manage configurations, and improve developer experience.
- There is an external dependency on the SnapWP Helper plugin installed on the WordPress server, which provides necessary hooks, additional functionality, and validates the WPGraphQL endpoints.
- Build and deployment workflows are handled via GitHub Actions (in .github/workflows) and local scripts (e.g., bin/publish-local.sh).

##### Important Patterns and Design Principles
- Composability: Separate packages allow developers to choose individual functionalities (e.g., query handling, block rendering, or Next.js configuration) and override parts as needed.
- Modularity: Each package focuses on a specific domain (core utilities, next integration, UI blocks, data querying), making the system easier to understand and maintain.
- Extensibility: The design facilitates granular overrides to extend or customize behaviors, emphasizing progressive enhancement rather than a monolithic architecture.
- Separation of Concerns: Distinct areas for frontend integration (Next.js), backend data management (GraphQL queries via @snapwp/query), and core utilities (@snapwp/core).

◦ Clear labels for each component (e.g., “Core”, “Next.js Integration”, “Block Renderer”, “GraphQL Query Engine”, “CLI/Tooling”).
▪ From WordPress (SnapWP Helper) to GraphQL Query Engine.
▪ From Core utilities to the various packages.
▪ From Next.js integration and Blocks rendering components pulling data through GraphQL.
◦ Annotations noting important configuration or deployment flows (GitHub workflows, build scripts, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["WordPress CMS (SnapWP Helper Plugin)"]:::external
    B["GraphQL Query Engine (@snapwp/query)"]:::coreLib
    C["Core Utilities (@snapwp/core)"]:::coreLib
    D["Next.js Integration (@snapwp/next)"]:::coreLib
    E["Block Management (@snapwp/blocks)"]:::coreLib

    subgraph "Developer Tooling"
        F1["CLI (@snapwp/cli)"]:::devTooling
        F2["Codegen Config (@snapwp/codegen-config)"]:::devTooling
        F3["ESLint Config (@snapwp/eslint-config)"]:::devTooling
        F4["Prettier Config (@snapwp/prettier-config)"]:::devTooling
    end

    G["Examples & Documentation"]:::examples

    subgraph "Infrastructure & Configuration"
        H1["GitHub Workflows"]:::infrastructure
        H2["Configuration Files"]:::infrastructure
        H3["Build Scripts"]:::infrastructure
    end

    A -->|"wpGraphQL"| B
    B -->|"provides"| E
    C -->|"integrates"| D
    C -->|"supports"| E
    C -->|"supports"| F1
    F1 -->|"triggers"| H1
    H1 -->|"references"| G

    classDef coreLib fill:#ED553B,stroke:#ED553B,stroke-width:2px;
    classDef devTooling fill:#3CAEA3,stroke:#3CAEA3,stroke-width:2px;
    classDef external fill:#F6D55C,stroke:#F6D55C,stroke-width:2px;
    classDef examples fill:#4ECDC4,stroke:#4ECDC4,stroke-width:2px;
    classDef infrastructure fill:#AC92EB,stroke:#AC92EB,stroke-width:2px;

    click C "https://github.com/rtcamp/snapwp/tree/develop/packages/core"
    click D "https://github.com/rtcamp/snapwp/tree/develop/packages/next"
    click E "https://github.com/rtcamp/snapwp/tree/develop/packages/blocks"
    click B "https://github.com/rtcamp/snapwp/tree/develop/packages/query"
    click F1 "https://github.com/rtcamp/snapwp/tree/develop/packages/cli"
    click F2 "https://github.com/rtcamp/snapwp/tree/develop/packages/codegen-config"
    click F3 "https://github.com/rtcamp/snapwp/tree/develop/packages/eslint-config"
    click F4 "https://github.com/rtcamp/snapwp/tree/develop/packages/prettier-config"
    click G "https://github.com/rtcamp/snapwp/tree/develop/examples/nextjs"
    click G "https://github.com/rtcamp/snapwp/tree/develop/docs"
    click H1 "https://github.com/rtcamp/snapwp/tree/develop/.github/workflows"
    click H2 "https://github.com/rtcamp/snapwp/tree/develop/config"
    click H3 "https://github.com/rtcamp/snapwp/blob/develop/bin/publish-local.sh"
```
