fse-architecture

name	fse-architecture
description	Oh My Brand! theme architecture and project structure. Directory layout, data flow, asset pipeline, and theme.json configuration. Use for understanding project organization.
metadata	{"author":"Wesley Smits","version":"1.0.0"}

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

1. WordPress Core loads first
2. Ollie Parent Theme functions.php
3. Oh My Brand! functions.php
4. theme.json merges (child overrides parent)
5. 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

• native-block-development - Block creation
• acf-block-registration - ACF blocks
• css-standards - CSS and theme.json tokens
• fse-git-workflow - Development workflow

---

References

• WordPress FSE Documentation
• theme.json Reference
• @wordpress/scripts