Developer Documentation

Welcome to the developer documentation for the Flavor ecosystem. These pages cover the three first-party products and everything you need to extend them: architecture, hooks and filters, the REST API, the module and page-builder systems, the design-token layer, logging, and the AI/abilities surface.

Product	What it is	Primary developer surface
Flavor Starter Theme (flavor-starter/)	Headless-first WordPress theme	Class-based Module System 2.0, the page builder (flavor_register_block()), the design-token layer, flavor_* hooks and the flavor/v1 REST namespace
WP eCommerce Core Plugin (wp-ecommerce-core/)	Performance-first eCommerce + native ERP	8-layer DDD stack, wpec_* hooks, and the ec/v1 REST namespace (commerce and ERP)
Flavor Core (flavor-core/)	License client, update manager, unified Debug logger, AI/abilities foundation	flavor_core_* helpers, the flavor-core/v1 debug API, the unified logger, and the flavor-mcp AI server

First-party developer docs

This documentation describes how Flavor is built and extended from the inside. The APIs, class contracts, hooks, and helpers here are an internal / first-party surface — accurate for building on Flavor itself (theme modules, plugin services, blocks, abilities, headless frontends, integrations). Ahead of public launch they are documented as "how our systems work," not a frozen third-party contract with long-term stability guarantees. Pin integrations to a store version and re-check after upgrades.

Architecture at a glance

The plugin and theme both use Domain-Driven Design (DDD) with a dependency-injection container. The plugin carries the deeper stack (it owns the full commerce + ERP domain); the theme runs a lighter DDD bootstrap around its module and builder systems.

Domain Layer         → Entities, Value Objects, Repository Interfaces
Application Layer     → Services, Business Logic, Use Cases
Infrastructure Layer  → Database Repositories, External APIs
Presentation Layer    → REST API Controllers, Admin UI, Storefront

The plugin's src/ tree has 8 top-level layers (see Repository Structure below and the full Architecture Overview).

Quick Links

Start here, then follow the area you need.

Architecture

• Architecture Overview — the DDD stack, both products' layers, and the database map
• DDD Layers — layer responsibilities and dependency direction
• Data Sovereignty — the three data domains and their helper functions
• Dependency Injection — the container, binding, and resolution

Debugging

• Debugging & Logging — the unified logger (flavor_log / wpec_log / flavor_core_log / window.flavorLog), channels, the FLAVOR_DEBUG gate, and the debug REST API

Hooks & Filters

• Hooks & Filters Overview — 150+ extension points, naming conventions
• Plugin Hooks — the wpec_* catalog
• Theme Hooks — the flavor_* catalog

REST API

• Commerce API — Overview — the three namespaces, authentication, and the built-in OpenAPI 3.0 spec
• Products · Orders · Cart · Authentication
• ERP API — Architecture — the entity → repository → service → controller pattern and integration listeners
• ERP API — Reference — the ERP endpoints (invoicing/myDATA, inventory, purchasing, accounting, CRM, HR)

Theme development

• Module Development — the class-based Module System 2.0 (AbstractModule)
• Creating a Module · Settings API · Best Practices
• Page-Builder Blocks — register a custom block with flavor_register_block()
• Design System & Tokens — the CSS-custom-property token layer

Flavor AI & Abilities

• Flavor MCP — Architecture — the read-only flavor-mcp server over the WordPress Abilities API
• Creating a Flavor AI Ability — the AbstractAbility contract, PII masking, and gating

Extension surface at a glance

Concrete, code-true counts for the current release. Follow the linked page for the detail — this table is only a map.

Surface	What you get	Where
Hooks & filters	150+ actions/filters — ≈90 in the plugin (wpec_*), ≈65 in the theme (flavor_*)	Hooks & Filters
REST API	3 namespaces — ec/v1 (37 controllers + a generated OpenAPI 3.0 spec), flavor/v1, flavor-core/v1	Commerce API · ERP API
Page-builder blocks	45+ built-in blocks; register your own via flavor_register_block()	Page Builder
Modules	Class-based Module System 2.0 — one AbstractModule subclass per module	Module Development
Design tokens	Two-layer CSS-custom-property system (--flavor-* base + --flavor-ds-* dynamic)	Design System
AI abilities	Read-only abilities exposed to AI agents through the flavor-mcp server (WP Abilities API)	Flavor AI

Data Sovereignty Principle

A critical concept: each product owns ALL of its data in its own custom tables — there are three data domains, and each has its own helper functions. Never reach for WordPress get_option() / update_option() for any of them.

// Plugin data — ALWAYS use helpers
wpec_get_option('key');            // NOT get_option('wpec_key')
wpec_set_option('key', 'value');   // NOT update_option('wpec_key')
wpec_cache_get('key');             // NOT get_transient('wpec_key')

// Theme data — ALWAYS use helpers
flavor_get_option('key');          // NOT get_option('flavor_options')
flavor_set_option('key', 'value'); // NOT update_option('flavor_options')
flavor_cache_get('key');           // NOT get_transient('flavor_key')

// Flavor Core data — ALWAYS use helpers
flavor_core_get_option('release_channel', 'stable');   // NOT get_option('flavor_core_*')
flavor_core_set_option('mcp_enabled', 'true');         // NOT update_option('flavor_core_*')

danger

Never use WordPress get_option() / update_option() / set_transient() for plugin, theme, or Flavor Core data. Always use the provided helpers. This is the #1 source of bugs — see Data Sovereignty for the full rules, tables, and the encrypted store.

Requirements for Development

Tool	Version
PHP	8.2+
Node.js	16+
Composer	2.x
WordPress	6.0+

note

The AI/abilities surface additionally requires WordPress 6.9+ (the WordPress Abilities API lives in core from 6.9) and Flavor Core 2.9.1+. See Flavor MCP — Architecture.

Repository Structure

├── flavor-starter/           # Theme
│   ├── inc/core/             # DDD bootstrap, Container, helpers
│   ├── inc/modules/          # Module System 2.0 (AbstractModule + ModuleManager)
│   ├── inc/builder/          # Page-builder BlockRegistry + block renderers
│   ├── inc/design-system.php # Design tokens (CSS custom properties)
│   ├── inc/translations.php  # flavor_t() / flavor_te() translation system
│   ├── react-app/            # Vite + React storefront
│   └── templates/            # PHP templates
│
├── wp-ecommerce-core/        # Plugin — 8 top-level src/ layers
│   ├── src/Application/       # Services, sanitization, use-case orchestration
│   ├── src/Domain/            # Entities (Product, Order, Invoice, Warehouse, …)
│   ├── src/Erp/               # ERP support: DB routing, integration sync listeners, onboarding
│   ├── src/Gateways/          # Payment drivers, couriers, myDATA, ΕΡΓΑΝΗ (top-level — NOT under Infrastructure)
│   ├── src/Infrastructure/    # Repositories, Database/migrations, Security
│   ├── src/Licensing/         # Tiered feature-gating (LicenseGate)
│   ├── src/Presentation/      # REST controllers (ec/v1), Admin screens, Storefront
│   ├── src/Support/           # Shared utilities / helpers
│   ├── includes/              # Bootstrap, Container, helpers
│   ├── admin/                 # Admin React app (@wordpress/scripts)
│   └── erp/                   # ERP SPA (Vite + React)
│
└── flavor-core/              # Flavor Core — the third product
    ├── includes/             # License client, update manager, unified Debug logger
    ├── includes/ai/          # AI abilities foundation (AbstractAbility) + flavor-mcp server
    └── admin/                # Debug Viewer SPA + licensing admin UI

Two structural facts that trip people up

In the plugin, gateways are top-level (src/Gateways/, not under Infrastructure), and repositories live in src/Infrastructure/Repositories/ (not Infrastructure/Persistence/). See Architecture Overview for the annotated tree.

The three REST namespaces

Each product registers its own namespace — ec/v1 (plugin, commerce + ERP), flavor/v1 (theme, storefront + page builder), and flavor-core/v1 (Flavor Core, the debug API). A separate MCP endpoint at /wp-json/flavor/mcp exposes read-only AI abilities. Details, authentication, and the OpenAPI spec are on the Commerce API — Overview.