How webmultipliers/examplepress works
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: theme Theme · README.md ExamplePress · theme-demo Theme Demo · theme-app Site apps
Components 14
Meta-repo
Repository-level index and documentation for the ExamplePress ecosystem.
- ExamplePress · Architecture hub that documents and wires the ExamplePress subsystem layout.
README.md - Docs · Repository documentation for routing, architecture, apps, block rendering, and distribution.
docs
Local site
WordPress-side runtime and modular app composition.
- Theme · Core site foundation that routes requests and orchestrates the runtime.
packages/theme - Router · Replaces WordPress template hierarchy with router-first dispatch.
packages/theme - Bootstrap · Initializes site environment and runtime context before rendering.
packages/theme - App hooks · Extension points where apps attach route-specific behavior and output.
packages/theme - Theme App · Boilerplate for building isolated WordPress plugins as ExamplePress apps.
packages/theme-app - Site apps · Business logic and route-specific content units that replace custom theme code.
packages/theme-app - Theme Demo · Reference composition showing theme, apps, routing, and blocks working together.
packages/theme-demo - Theme Updater · Out-of-band recovery path for patching the theme independently of the main runtime.
packages/theme-update - WordPress · Underlying CMS host that loads the theme and plugins.
Distribution
Licensing, release browsing, and update delivery via Troy.
- Troy Bridge · 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 · Filesystem-driven block registration and rendering through block.json and PHP templates.
- Troy Server · Central service for licensing and distribution of versioned releases.
Connections 21
- 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.