Architecture Overview

This document provides a high-level overview of the LamaPress architecture, explaining how the different parts of the system work together.

Table of Contents

• Overview
• System Architecture
  • Component-Based Structure
  • Data Flow
  • Template System
• Directory Structure
  • Components
  • Functions
  • Configuration
  • Source Files
• Core Concepts
  • Sections, Blocks, and Parts
  • ACF Integration
  • JavaScript Architecture
  • Styling System
• Request Lifecycle
• Related Documentation

---

Overview

LamaPress is a component-based WordPress theme boilerplate that emphasizes:

• Modularity: Components are self-contained and reusable
• Separation of Concerns: PHP, JavaScript, and SCSS are organized by component
• Developer Experience: Helper functions simplify common tasks
• Performance: Optimized build process and code splitting
• Maintainability: Clear structure and consistent patterns

System Architecture

Component-Based Structure

LamaPress organizes UI into three component types:

1. Sections (components/sections/) - Full-width page sections
2. Blocks (components/blocks/) - Reusable UI components
3. Parts (components/parts/) - Atomic components (buttons, icons, etc.)

Each component can contain:

• index.php - Template file (required)
• acf.php - ACF field definitions (required for sections, optional for blocks/parts)
• index.js - JavaScript class (optional)
• style.scss - Component-specific styles (optional)
• functions.php - Section-specific functions (optional, sections only)

Data Flow

ACF Fields → Templates → Sections → Blocks → Parts

1. ACF Fields are defined in component acf.php files
2. Templates (components/templates/) load sections using llSection()
3. Sections load blocks using llBlock() and parts using llPart()
4. Blocks and Parts receive data as props

Template System

Templates (components/templates/) are page-level files that:

• Use llStartTemplate() to begin output buffering
• Load sections with llSection(name, key)
• Use llEndTemplate() to wrap content in layout block

See Templates System for details.

Directory Structure

Components

components/
├── sections/     # Full-width page sections
├── blocks/       # Reusable UI components
├── parts/        # Atomic components
└── templates/    # Page templates

Functions

functions/
├── includes.php              # Core helper functions
├── register-section-fields.php  # ACF field registration
├── post-types.php            # Custom post type registration
├── taxonomies.php            # Custom taxonomy registration
└── ...                       # Other function files

Configuration

config/
├── post-types.php        # Post type definitions
├── taxonomies.php        # Taxonomy definitions
├── post-templates.php    # Template mappings
├── fields/              # Global ACF fields
└── ...                  # Other configuration files

Source Files

src/
├── js/                  # JavaScript source files
│   ├── core/           # Core system files
│   ├── components/     # Component JavaScript
│   └── scripts.js      # Main entry point
└── scss/               # SCSS source files
    ├── base/           # Base styles
    ├── sections/       # Section styles
    └── styles.scss     # Main entry point

Core Concepts

Sections, Blocks, and Parts

• Sections: Full-width page components (e.g., hero, content sections)
• Blocks: Reusable UI components (e.g., rich content, image slider)
• Parts: Atomic components (e.g., buttons, icons, images)

See Component System for details.

ACF Integration

ACF fields are automatically registered from component acf.php files:

• Section fields are grouped by template
• Block/part fields can be reused via llGetFields()
• Fields are accessed using llField(), llFields(), or llGetFields()

See ACF Integration for details.

JavaScript Architecture

JavaScript components are automatically loaded via data-component attributes:

• Components export default classes
• Lifecycle methods: constructor(), init(), bindEvents(), enter(), destroy()
• Core instances provide shared functionality (Router, Scroller, Device, etc.)

See JavaScript Architecture for details.

Styling System

LamaPress uses Tailwind CSS with custom design system:

• Typography system (ll-{category}-{size} classes)
• Color system (theme-based CSS variables)
• Grid system (ll-grid class with column utilities)
• Spacing system (responsive spacing utilities)

See Styling System for details.

Request Lifecycle

1. WordPress Initialization

   • WordPress core loads
   • Theme functions are loaded
   • ACF fields are registered from component files

2. Template Selection

   • WordPress selects template based on page type
   • Template file (components/templates/*.php) is loaded

3. Template Execution

   • llStartTemplate() begins output buffering
   • Sections are loaded with llSection(name, key)
   • ACF fields are retrieved for each section
   • llEndTemplate() wraps content in layout block

4. Component Rendering

   • Section templates render HTML
   • Blocks and parts are loaded with llBlock() and llPart()
   • Data flows from sections to blocks to parts

5. JavaScript Initialization

   • Vite injects JavaScript bundle
   • App class initializes core instances
   • Components with data-component attributes are automatically loaded
   • Page transitions are set up (Swup)

6. Component Lifecycle

   • Components call init() for setup
   • bindEvents() attaches event listeners
   • enter() triggers reveal animations
   • destroy() cleans up on page transitions

Related Documentation

• Component System - Component structure and usage
• JavaScript Architecture - JavaScript system details
• ACF Integration - ACF field system
• Templates System - Template hierarchy
• PHP Functions Reference - Helper functions
• Styling System - Styling approach

---

Next Steps:

• Read Component System to understand component structure
• Review JavaScript Architecture for JavaScript details
• Check Templates System for template usage