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 — what's stable vs what evolves

This documentation describes how Flavor is built and extended from the inside, for building on Flavor itself (theme modules, plugin services, blocks, abilities, headless frontends, integrations). Not every surface carries the same stability guarantee:

• Committed (follow semantic versioning): the hooks and filters marked Stable in the Hooks reference, plus the ERP integration seams. Breaking changes to these ship only on a major version, announced in the changelog.
• Evolving: REST routes, class / internal APIs, and hooks not yet marked Stable. These can change between releases as the product matures.

For anything mission-critical, prefer the Stable surfaces, see the full Stability & Versioning policy, pin your integration 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.