Visual Architecture Diagrams

Created: 2026-04-08 Status: IDEA

Problem

The documentation is text-heavy. Key architectural concepts like data flow, component hierarchies, and state management are hard to grasp without visual aids. Diagrams with boxes, arrows, and hierarchies would significantly improve comprehension.

Proposed Diagrams

1. Data Flow Overview

Show the full pipeline with boxes and arrows:

Application-Frontend (Vuex) → Application-Backend → Creative-Composer → Creative-Engine (DataStore)

• What data lives where
• Which direction data flows (unidirectional)
• How the iframe boundary separates Frontend Vuex from Engine DataStore

2. Block & Component Hierarchy

Creative
  ├── creativeProperties (name, format, type)
  ├── logicSettings (flow/operators)
  └── creativeBlocks
      ├── textProperties-1 (visual element, multiple instances)
      ├── graphicProperties-1
      ├── buttonProperties-1
      ├── formProperties (specialized, single instance)
      │   ├── formInputProperties-1 (sub-block)
      │   └── formButtonProperties-1 (sub-block)
      ├── sliderProperties
      │   └── slides[] (sub-blocks)
      └── videoProperties

3. Operator → Block Resolution

How flow operators target blocks — the abbreviation system:

Flow Editor                    Block System
targetAbbrevOpName: "g1"  →   classNameFromBlockName("graphicProperties-1") = "g1"
                           →   getBlockByName("graphicProperties-1")
                           →   block data (image URL, styles, etc.)

This is currently undocumented and spread across multiple files.

4. Vuex Store Module Map

Vuex Root
  ├── auth (user, permissions)
  ├── builder (active creative, master/child, preview state)
  ├── blocks (creativeBlocks, creativeProperties, selectedBlockPath)
  ├── creatives (creative list)
  ├── preview (iframe state)
  └── ... (18+ modules)

5. Builder Tab Architecture

Builder
  ├── Visuals Tab
  │   ├── Left: Block List (AddBlockTool)
  │   ├── Center: Preview (iframe → Creative-Engine)
  │   └── Right: Configuration Panel (*Configuration.vue → configurationLogic mixin)
  ├── Flow Tab
  │   └── CavaiFlow → OperatorBase → *Op.vue components
  └── Delivery Tab

Format Considerations

• Could use Mermaid diagrams (renderable in markdown)
• Animated diagrams for data flow sequences (e.g. what happens when an operator fires)
• Interactive diagrams if the documentation platform supports it
• Color coding: Frontend = blue, Backend = green, Engine = orange

Documentation Gaps Found (2026-04-08)

These topics are not well documented and should be addressed:

1. Block abbreviation system — how classNameFromBlockName() works, where it's used, the full mapping logic. Currently spread across Blocks/utils.ts, TargetOpSelector.vue, and OperatorBase.vue with no central reference.

2. Operator ↔ Block data access — how operators (in the Flow tab) can read/write block data (in the Visuals tab). The blocks Vuex module getters are powerful but undocumented for operator use cases.

3. Block property schemas — what properties each block type has (e.g. where does graphicProperties store its image URL?). defaults.ts has the defaults but there's no reference doc listing all properties per block type.