FSE Architecture
Project architecture and structure for the Oh My Brand! WordPress FSE theme.
When to Use
- Understanding the project directory structure
- Locating files and understanding their purpose
- Understanding how blocks are organized
- Understanding the build process and asset flow
- Configuring theme.json settings
Reference Files
| File | Purpose |
|---|
| theme.json | theme.json structure and tokens |
Project Structure
oh-my-brand/
├── AGENT.md # AI assistant guidelines
├── functions.php # Theme setup, hooks, registration
├── style.css # Theme metadata (required by WP)
├── theme.json # Global styles, settings, blocks
│
├── src/ # Source files (@wordpress/scripts)
│ └── blocks/ # Native WordPress blocks
│ ├── gallery/ # Gallery carousel block
│ ├── faq/ # FAQ accordion block
│ └── utils/ # Shared utilities
│
├── build/ # Compiled output (generated)
│ └── blocks/ # Built block assets
│
├── blocks/ # ACF custom blocks
│ ├── acf-faq/ # FAQ ACF block
│ └── acf-gallery-block/# Gallery ACF block
│
├── assets/ # Static assets
│ ├── css/ # Global stylesheets
│ ├── js/ # Compiled JavaScript
│ └── icons/ # SVG icons
│
├── includes/ # PHP includes
│ ├── assets.php # Asset registration
│ └── block-helpers.php # Block utilities
│
├── acf-json/ # ACF field groups (auto-sync)
├── patterns/ # Block patterns
├── tests/ # Test files
└── docs/ # Documentation
Theme Architecture
Parent-Child Relationship
WordPress Core
│
▼
Ollie Parent Theme
• Base FSE templates
• Default block styles
│
▼
Oh My Brand! Child Theme
• Custom blocks (native + ACF)
• Extended theme.json
• Brand-specific styles
File Loading Order
- WordPress Core loads first
- Ollie Parent Theme
functions.php
- Oh My Brand!
functions.php
- theme.json merges (child overrides parent)
- Block assets loaded per-block when rendered
Block Organization
Native Blocks (src/blocks/)
Built with @wordpress/scripts, compiled to build/blocks/:
| File | Purpose |
|---|
block.json | Block metadata |
index.js | Registration entry |
edit.tsx | Editor component |
render.php | Server-side render |
helpers.php | Helper functions |
style.css | Frontend styles |
view.ts | Frontend Web Component |
ACF Blocks (blocks/)
ACF PRO blocks, not compiled:
| File | Purpose |
|---|
block.json | ACF block metadata |
render.php | Render template |
helpers.php | Helper functions |
style.css | Block styles |
Key Differences
| Aspect | Native Block | ACF Block |
|---|
| Location | src/blocks/ | blocks/ |
| Name prefix | theme-oh-my-brand/ | acf/ |
| Data source | $attributes | get_field() |
| Editor UI | React component | ACF fields |
| Build | Required | Not required |
Asset Pipeline
Build Process
Source Build Output
────── ────────────
src/blocks/gallery/
├── index.js → build/blocks/gallery/
├── edit.tsx ├── index.js
├── view.ts ├── view.js
├── style.css ├── style-index.css
└── editor.css └── index.css
Commands
| Command | Purpose |
|---|
pnpm run build | Production build |
pnpm run start | Watch mode |
pnpm run lint | Run all linters |
Asset Loading
| Property | When Loaded |
|---|
style | Block rendered (frontend + editor) |
editorStyle | Block in editor |
viewScript | Block on frontend page |
Data Flow
Native Block Data Flow
block.json (attributes) → edit.tsx (editor state)
↓
$attributes (saved to post)
↓
render.php (server render)
↓
view.ts (frontend interactivity)
ACF Block Data Flow
ACF Field Group (acf-json/) → WordPress Editor (ACF forms)
↓
get_field() (post meta)
↓
render.php (server render)
theme.json Configuration
Structure
See theme.json for complete structure example.
Design Tokens
| Token Type | CSS Variable |
|---|
| Colors | var(--wp--preset--color--primary) |
| Spacing | var(--wp--preset--spacing--20) |
| Typography | var(--wp--preset--font-family--body) |
| Layout | var(--wp--style--global--content-size) |
Related Skills
References
