# webmultipliers/examplepress architecture

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

- Interactive diagram: https://gitdiagram.com/webmultipliers/examplepress
- Repository: https://github.com/webmultipliers/examplepress

## Overview

1. **Repository role**
   - This repo is a **meta-repository / architecture hub** for ExamplePress.
   - The only original content here is the `docs/` folder and `README.md`; everything under `packages/` and `vendor/` is a **Git submodule** pointing to upstream repos.
   - So the architecture diagram should treat this repo as an **index of subsystems**, not a single deployable app.

2. **Top-level architectural shape**
   - ExamplePress is organized around **three major concerns**:
     - **Infrastructure**: the WordPress theme and its standalone updater.
     - **Application layer**: reusable app templates and sample apps.
     - **Distribution**: Troy-based fleet update and licensing flow.
   - The system is explicitly **router-first**, replacing the standard WordPress template hierarchy.

3. **Core runtime: `theme`**
   - `packages/theme` is the foundation of a site.
   - It acts like an **operating system for the WordPress instance**: it routes requests, orchestrates bootstrap/environment setup, and exposes hooks for apps to render content.
   - This is the main entry point for request handling on a site using ExamplePress.

4. **Application layer: `theme-app` and site apps**
   - `packages/theme-app` is a **boilerplate/template for creating apps**.
   - In ExamplePress, an “app” is a standard **WordPress plugin** with isolated responsibilities.
   - Apps are meant to hold the business logic and route-specific content rendering instead of placing custom code in `functions.php`.

5. **Reference implementation: `theme-demo`**
   - `packages/theme-demo` is a **full example site/application composition**.
   - It shows how the theme, apps, routing, and block rendering fit together in a realistic setup.
   - For an architecture diagram, it is best represented as an **integration/example environment**, not a platform dependency.

6. **Routing model**
   - The architecture replaces WordPress’s default template resolution with a **custom router-driven flow**.
   - Requests are dispatched by the theme/router first, then handed off to the relevant app or rendering hook.
   - This means the main control boundary is: **request enters theme → router resolves route → app or block content is rendered**.

7. **Content rendering: Blockstudio**
   - `vendor/blockstudio` is the rendering engine used across the ecosystem.
   - Its key architectural trait is **filesystem-based block registration**: a `block.json` plus a PHP template is enough to define and render blocks.
   - This removes the need for a Node/Webpack build pipeline and makes block definitions part of the PHP/theme filesystem.

8. **Distribution and fleet management: `troy-bridge` + Troy**
   - `packages/troy-bridge` is the **client-side connector installed on a site**.
   - It talks to the external **Troy server** (`vendor/troy`) to browse releases, verify licenses, and pull app updates.
   - Architecturally this creates a **site ↔ central hub** boundary: connected sites consume updates from Troy rather than relying on WordPress.org distribution.

9. **Theme updater: separate resilience path**
   - `packages/theme-update` is a **standalone updater for the theme**.
   - It is intentionally decoupled so it can still operate if the main theme has a fatal error.
   - In diagrams, this should be shown as an **out-of-band recovery/update path** distinct from normal site runtime.

10. **How the parts connect**
   - A typical runtime flow is:
     - WordPress loads the **ExamplePress theme**.
     - The theme routes the request and sets up the environment.
     - A **site app plugin** handles route-specific logic and renders content.
     - Rendering may use **Blockstudio** blocks from the filesystem.
   - A separate operational flow exists for updates:
     - The site’s **Troy Bridge** checks the central **Troy server**.
     - It authenticates/licenses and downloads versioned releases.
     - The **theme updater** can patch the theme independently if needed.

11. **What is inside vs. outside the boundary**
   - Inside the ExamplePress ecosystem: theme, updater, app template, demo, Troy bridge.
   - Outside but integrated: **Blockstudio** and **Troy** as upstream dependencies/services.
   - This boundary matters because the repository is not implementing those external systems; it is documenting and wiring to them.

12. **Best diagram interpretation**
   - Draw this as a **site platform with a central distribution plane**:
     - A local **WordPress site** contains the theme, apps, updater, and block rendering.
     - A remote **Troy service** handles distribution and licensing.
     - The theme is the orchestration layer, apps are the modular business/content units, and Blockstudio is the rendering engine.

Main entry points: [`packages/theme`](https://github.com/webmultipliers/examplepress/tree/development/packages/theme) (Theme), [`README.md`](https://github.com/webmultipliers/examplepress/blob/development/README.md) (ExamplePress), [`packages/theme-demo`](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-demo) (Theme Demo), [`packages/theme-app`](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-app) (Site apps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_meta["Meta-repo"]
  node_repo["ExamplePress<br/>meta-repo<br/>[README.md]"]
  node_docs["Docs"]
end

subgraph group_site["Local site"]
  node_theme["Theme"]
  node_router["Router"]
  node_bootstrap["Bootstrap<br/>env setup"]
  node_hooks(("App hooks<br/>render hooks"))
  node_themeapp["Theme App<br/>app template"]
  node_apps["Site apps<br/>wp plugins"]
  node_demo["Theme Demo<br/>example site"]
  node_updater["Theme Updater<br/>standalone updater"]
  node_wp(("WordPress<br/>host platform"))
end

subgraph group_dist["Distribution"]
  node_bridge["Troy Bridge<br/>client connector"]
end

subgraph group_external["External"]
  node_blocks["Blockstudio<br/>block runtime"]
  node_troy[("Troy Server<br/>release hub")]
end

node_repo -->|"documents"| node_docs
node_repo -->|"indexes"| node_theme
node_repo -->|"indexes"| node_themeapp
node_repo -->|"indexes"| node_demo
node_repo -->|"indexes"| node_updater
node_repo -->|"indexes"| node_bridge
node_wp -->|"loads"| node_theme
node_theme -->|"routes"| node_router
node_theme -->|"initializes"| node_bootstrap
node_router -->|"dispatches"| node_hooks
node_themeapp -->|"scaffolds"| node_apps
node_apps -->|"renders via"| node_hooks
node_apps -->|"uses"| node_blocks
node_theme -->|"renders via"| node_blocks
node_demo -->|"showcases"| node_theme
node_demo -->|"showcases"| node_apps
node_demo -->|"showcases"| node_blocks
node_bridge -->|"connects to"| node_troy
node_bridge -->|"feeds"| node_updater
node_updater -->|"patches"| node_theme
node_troy -->|"serves"| node_bridge

click node_repo "https://github.com/webmultipliers/examplepress/blob/development/README.md"
click node_docs "https://github.com/webmultipliers/examplepress/tree/development/docs"
click node_theme "https://github.com/webmultipliers/examplepress/tree/development/packages/theme"
click node_router "https://github.com/webmultipliers/examplepress/tree/development/packages/theme"
click node_bootstrap "https://github.com/webmultipliers/examplepress/tree/development/packages/theme"
click node_hooks "https://github.com/webmultipliers/examplepress/tree/development/packages/theme"
click node_themeapp "https://github.com/webmultipliers/examplepress/tree/development/packages/theme-app"
click node_apps "https://github.com/webmultipliers/examplepress/tree/development/packages/theme-app"
click node_demo "https://github.com/webmultipliers/examplepress/tree/development/packages/theme-demo"
click node_updater "https://github.com/webmultipliers/examplepress/tree/development/packages/theme-update"
click node_bridge "https://github.com/webmultipliers/examplepress/tree/development/packages/troy-bridge"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo,node_docs toneBlue
class node_theme,node_router,node_bootstrap,node_hooks,node_themeapp,node_apps,node_demo,node_updater,node_wp toneAmber
class node_bridge toneMint
class node_blocks,node_troy toneRose
```

## Components

### Meta-repo

Repository-level index and documentation for the ExamplePress ecosystem.

- [ExamplePress](https://github.com/webmultipliers/examplepress/blob/development/README.md): meta-repo · Architecture hub that documents and wires the ExamplePress subsystem layout. · `README.md`
- [Docs](https://github.com/webmultipliers/examplepress/tree/development/docs): spec docs · Repository documentation for routing, architecture, apps, block rendering, and distribution. · `docs`

### Local site

WordPress-side runtime and modular app composition.

- [Theme](https://github.com/webmultipliers/examplepress/tree/development/packages/theme): wp theme · Core site foundation that routes requests and orchestrates the runtime. · `packages/theme`
- [Router](https://github.com/webmultipliers/examplepress/tree/development/packages/theme): request router · Replaces WordPress template hierarchy with router-first dispatch. · `packages/theme`
- [Bootstrap](https://github.com/webmultipliers/examplepress/tree/development/packages/theme): env setup · Initializes site environment and runtime context before rendering. · `packages/theme`
- [App hooks](https://github.com/webmultipliers/examplepress/tree/development/packages/theme): render hooks · Extension points where apps attach route-specific behavior and output. · `packages/theme`
- [Theme App](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-app): app template · Boilerplate for building isolated WordPress plugins as ExamplePress apps. · `packages/theme-app`
- [Site apps](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-app): wp plugins · Business logic and route-specific content units that replace custom theme code. · `packages/theme-app`
- [Theme Demo](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-demo): example site · Reference composition showing theme, apps, routing, and blocks working together. · `packages/theme-demo`
- [Theme Updater](https://github.com/webmultipliers/examplepress/tree/development/packages/theme-update): standalone updater · Out-of-band recovery path for patching the theme independently of the main runtime. · `packages/theme-update`
- **WordPress**: host platform · Underlying CMS host that loads the theme and plugins.

### Distribution

Licensing, release browsing, and update delivery via Troy.

- [Troy Bridge](https://github.com/webmultipliers/examplepress/tree/development/packages/troy-bridge): client connector · Site-side connector that checks releases, verifies licenses, and downloads updates. · `packages/troy-bridge`

### External

Upstream systems integrated by ExamplePress but not implemented here.

- **Blockstudio**: block runtime · Filesystem-driven block registration and rendering through block.json and PHP templates.
- **Troy Server**: release hub · Central service for licensing and distribution of versioned releases.

## Connections

- ExamplePress → Docs: documents · Repository README and docs describe the architecture and subsystems.
- ExamplePress → Theme: indexes · Meta-repo points to the theme subsystem as the core runtime.
- ExamplePress → Theme App: indexes · Meta-repo points to the app template used to build site plugins.
- ExamplePress → Theme Demo: indexes · Meta-repo includes the integration/example site composition.
- ExamplePress → Theme Updater: indexes · Meta-repo includes the standalone theme recovery/update path.
- ExamplePress → Troy Bridge: indexes · Meta-repo includes the client connector for Troy-based distribution.
- WordPress → Theme: loads · WordPress hosts the ExamplePress theme.
- Theme → Router: routes · Theme begins request handling with custom routing.
- Theme → Bootstrap: initializes · Theme sets up the execution environment and context.
- Router → App hooks: dispatches · Resolved routes flow into render hooks and app integration points.
- Theme App → Site apps: scaffolds · Template defines how new apps are structured.
- Site apps → App hooks: renders via · Apps attach to the theme through route and render hooks.
- Site apps → Blockstudio: uses · Apps can render content using filesystem-defined blocks.
- Theme → Blockstudio: renders via · Theme delegates block rendering to Blockstudio.
- Theme Demo → Theme: showcases · Demo composes the theme into a realistic site setup.
- Theme Demo → Site apps: showcases · Demo includes representative app/plugin behavior.
- Theme Demo → Blockstudio: showcases · Demo demonstrates block-based rendering in practice.
- Troy Bridge → Troy Server: connects to · Bridge talks to the central Troy service for releases and licensing.
- Troy Bridge → Theme Updater: feeds · Distribution flow provides versioned releases to the theme updater.
- Theme Updater → Theme: patches · Standalone updater can repair or update the theme independently.
- Troy Server → Troy Bridge: serves · Troy is the remote source of licensed releases and update metadata.
