# p3ol/oak architecture

> Architecture diagram of the GitHub repository p3ol/oak, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p3ol/oak
- Repository: https://github.com/p3ol/oak

## Overview

##### Project Type and Purpose
- This is an open-source, modular, block-based page‐builder framework (“Oak”) published as a monorepo of NPM packages.
- Its core offers the builder abstraction and plugin system; separate packages provide React rendering, theming, rich-text addons (Remirror/CKEditor5), and a Strapi integration plugin.

##### File Structure Analysis
- Top‐level: CI/CD config (`.github/workflows/`, `.ci/`), build scripts (`lerna.json`, `package.json`), Storybook examples (`.storybook/`), TypeScript configs.
- `packages/` folder holds:
- `core` – the fundamental builder engine (builder, fields, store, events, types)
- `react` – React renderer layer, UI components, hooks, stories, tests
- `theme` – base CSS/SASS definitions and theming scripts
- `addon-remirror` & `addon-ckeditor5-react` – two pluggable rich-text field implementations
- `strapi-plugin` – Strapi CMS plugin glue for Oak fields
- `ckeditor5-build-custom` – custom CKEditor5 build with Oak plugin extensions

##### Core Components
- Monorepo Root & Tooling
- Lerna/Yarn Workspaces – orchestrates package interdependencies and publishes
- CI/CD (GitHub Actions, Jest, Codecov)
- Storybook – example runner for UI components
- Oak Core Package
- Builder Engine – orchestrates blocks, settings, store, overrides
- Addon Interface – the API that addons implement
- Renderer Layer
- React Renderer – converts Core builder definitions into React components
- Theme Layer – SASS/CSS that styles React components
- Rich-Text Addons
- Remirror addon – implements WYSIWYG via Remirror
- CKEditor5 addon – implements WYSIWYG via CKEditor5
- External Integrations
- Strapi Plugin – Strapi admin/ backend adapters that wrap Oak fields for CMS use

##### Relationships & Data Flows
- React Renderer imports theme assets and calls Core APIs at runtime
- Strapi Plugin depends on Core to render configuration in Strapi admin, and on React Renderer for UI
- CI/CD connects to monorepo root (build/test → publish)

##### Architectural Patterns & Design Principles
- Modular monorepo (Lerna/Yarn Workspaces)
- Plugin architecture (Core defines extension points; addons implement and register)
- Separation of concerns: Core (logic) vs Renderer (view/UI) vs Theme (styling)
- Single‐source maintenance of builds and scripts at root level

##### Relevant Technologies
- Node.js + TypeScript
- Lerna & Yarn Workspaces for package management
- Rollup & Webpack configs per package for bundling
- Storybook for UI examples
- Jest for unit testing
- GitHub Actions for CI/CD
- Remirror & CKEditor5 as external rich-text engines
- Strapi as external CMS

f. Above, show CI/CD → Run tests/build → publish to NPM registry.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root and Tooling
    subgraph "Monorepo Root"
        direction TB
        LernaWorkspaces["Lerna / Yarn Workspaces"]:::tooling
        CICD["CI/CD (GitHub Actions, Jest)"]:::ci
        Storybook["Storybook Examples"]:::tooling

        subgraph "Packages"
            direction TB
            Core["Oak Core Package"]:::oakPackage
            React["React Renderer Layer"]:::oakPackage
            Theme["Theme Layer"]:::oakPackage
            AddonRemirror["Remirror Rich-Text Addon"]:::addon
            AddonCKEditor["CKEditor5 Rich-Text Addon"]:::addon
            CKCustom["Custom CKEditor5 Build"]:::addon
            StrapiPlugin["Strapi Integration Plugin"]:::oakPackage
        end
    end

    %% External Systems
    StrapiCMS["Strapi CMS"]:::external
    NPMRegistry["NPM Registry"]:::external

    %% Connections
    CICD -->|"triggers build/test"| LernaWorkspaces
    LernaWorkspaces -->|"manages packages"| Core
    LernaWorkspaces --> React
    LernaWorkspaces --> Theme
    LernaWorkspaces --> AddonRemirror
    LernaWorkspaces --> AddonCKEditor
    LernaWorkspaces --> CKCustom
    LernaWorkspaces --> StrapiPlugin
    LernaWorkspaces -->|"publishes"| NPMRegistry

    Core -->|"renders via"| React
    React -->|"styles injected"| Theme

    AddonRemirror -->|"registers plugin"| Core
    AddonCKEditor -->|"registers plugin"| Core
    CKCustom -->|"extends CKEditor"| AddonCKEditor

    StrapiPlugin -->|"depends on core"| Core
    StrapiPlugin -->|"uses renderer UI"| React
    StrapiPlugin -->|"integrates with"| StrapiCMS

    %% Click Events
    click LernaWorkspaces "https://github.com/p3ol/oak/blob/master/package.json"
    click CICD "https://github.com/p3ol/oak/blob/master/.github/workflows/ci.yml"
    click Storybook "https://github.com/p3ol/oak/blob/master/.storybook/main.ts"
    click Core "https://github.com/p3ol/oak/tree/master/packages/core/lib"
    click React "https://github.com/p3ol/oak/tree/master/packages/react/lib"
    click Theme "https://github.com/p3ol/oak/tree/master/packages/theme/lib"
    click AddonRemirror "https://github.com/p3ol/oak/tree/master/packages/addon-remirror/lib"
    click AddonCKEditor "https://github.com/p3ol/oak/tree/master/packages/addon-ckeditor5-react/lib"
    click CKCustom "https://github.com/p3ol/oak/tree/master/packages/ckeditor5-build-custom/lib"
    click StrapiPlugin "https://github.com/p3ol/oak/tree/master/packages/strapi-plugin/lib"

    %% Styles
    classDef tooling fill:#FFF4E5,stroke:#D69D19
    classDef ci fill:#E6FFED,stroke:#28A745
    classDef oakPackage fill:#D0E8FF,stroke:#0366D6
    classDef addon fill:#E8F1FF,stroke:#0366D6
    classDef external fill:#EEEEEE,stroke:#666666
```
