Engine Core - Computation, Overrides & Scripting

The core engine that powers Campaign Manager - computation graph, dependency resolution, override system, scripting

1. The Computation Engine

This is the heart of Campaign Manager. When you trigger a computation, here is what happens internally:

Full Computation Flowchart

flowchart TD
    Trigger["User triggers computation"] --> Load["Load all data from DB:
campaign -> phases -> steps -> CC items + env vars"]
    Load --> BuildGraph["Build dependency graph
(analyze foreign keys)"]
    BuildGraph --> ResolveEnv["Compute environment variables
(in order: strings, JSON, functions)"]
    ResolveEnv --> TopoSort["Determine execution order
(topological sort by dependencies)"]
    TopoSort --> ThreadPool["Allocate thread pool
(up to 30 threads per campaign)"]
    ThreadPool --> Execute{"Execute each variable"}
    Execute -->|AI prompt| LLM["Call LLM provider
(rate-limited, with retries)"]
    Execute -->|Function| JS["Execute JavaScript
(with full context)"]
    Execute -->|Asset| Render["Render document template
+ store file to S3"]
    Execute -->|Static| Direct["Use stored value"]
    LLM --> Store["Store result, update state"]
    JS --> Store
    Render --> Store
    Direct --> Store
    Store --> WS["Send WebSocket update
(real-time progress)"]
    WS --> Next{"More variables?"}
    Next -->|Yes| Execute
    Next -->|No| Done["Computation complete"]
    Done --> AutoDeploy{"Auto-deploy configured?"}
    AutoDeploy -->|Yes| Deploy["Deploy assets to microsite"]
    AutoDeploy -->|No| Finish["Done"]

Dependency Resolution - How Variables Connect

Each variable declares what other variables it depends on (its "foreign keys"). The system supports three dependency styles:

Computation Scopes

Computation Modes

Downstream Propagation

When you recompute a single variable, you choose how far the effects ripple:

Reset Options (How to Handle Existing Results)

Error Handling During Computation

Thread Pool Management

Auto-Publishing After Computation

Asset Generation Pipeline (7 Steps)

When an asset-type variable is computed, here is what happens:

1. The system loads the associated document template (XSL, FreeMarker, or static HTML)
2. It collects all computed variable values from the step as template context
3. The template is rendered into a final document (HTML, PDF, etc.)
4. The generated file is stored in the company's public S3 storage
5. If the output is HTML, a PDF version is also generated automatically
6. An Asset record is created with the file reference and deployment path
7. Based on the publishing stage, the asset may be auto-deployed to the microsite

Real-Time WebSocket Updates

During computation, the system sends real-time events via WebSocket:

The Customer App polls computation status every 2 seconds and auto-refreshes step data when computation completes.

Startup Recovery

2. Override & Precedence System

One of the most complex and least visible aspects of the system. Understanding who overrides whom is critical for product decisions.

CC Item Value Hierarchy

Every CC Item can have up to three values. The resultType field determines which value is returned:

flowchart TD
    Compute["AI/Function computes value"] --> Result["result
(original computed value)"]
    User["User manually overrides"] --> ResultOvr["resultOvr
(user override)"]
    AI2["AI merges original + override"] --> Patched["patched
(AI-merged version)"]

    Result --> Decision{"resultType?"}
    ResultOvr --> Decision
    Patched --> Decision

    Decision -->|ORIGINAL| UseResult["Return: result"]
    Decision -->|OVERRIDE| UseOvr["Return: resultOvr
(if exists, else result)"]
    Decision -->|PATCHED| UsePatched["Return: patched"]

    style UsePatched fill:#EEEEFD,stroke:#623CEA
    style UseOvr fill:#F4FBFF,stroke:#22B5FF
    style UseResult fill:#F7F7F7,stroke:#D4DAE0

Chat Override Flow

sequenceDiagram
    participant User
    participant Chat as Chat Interface
    participant System
    participant CCItem as CC Item (Variable)

    User->>Chat: Asks AI to suggest values
    Chat->>System: AI generates suggestions
    System->>System: Create ChatOverride (status: READY)
    System-->>Chat: Show suggestions to user

    alt User accepts
        User->>Chat: Clicks "Apply"
        Chat->>System: Set ChatOverride status = APPLIED
        System->>CCItem: Set resultOvr = suggestion value
        System->>CCItem: Set resultType = OVERRIDE
        Note over CCItem: Variable now returns
user-approved AI suggestion
    else User rejects
        User->>Chat: Clicks "Cancel"
        Chat->>System: Set ChatOverride status = CANCELED
        Note over CCItem: Variable unchanged
    end

Chat overrides are the bridge between conversational AI and campaign data. The key insight: the AI suggestion doesn't change anything until the user explicitly applies it. This is a safety mechanism.

AI Model Resolution Chain

flowchart LR
    V["Variable-specific
model"] -->|if null| E["Env var prompt
model"]
    E -->|if null| C["Campaign default
model"]
    C -->|if null| S["System default
model"]
    S -->|if null| Err["Error:
No model found"]

    style V fill:#EEEEFD,stroke:#623CEA
    style Err fill:#FFF2F2,stroke:#DC2626

Each level is optional. The system walks the chain until it finds a model. If nothing is configured at any level, computation fails with "AI model not defined".

Downstream Reset & Override Protection

When the system resets variables for recomputation, it respects overrides:

3. Scripting Engine

Function-type CC items and environment variables execute JavaScript (Nashorn engine, ECMAScript 5.1). Scripts have access to the full computation context through injected wrapper objects.

Available API Objects

llmApi - AI Model Access

agentsApi - AI Agents (A2A)

AgentSession usage:

var session = agentsApi.session("writing_orchestrator", campaignId);
var first = session.send("Write a blog post about AI");
var refined = session.send("Make it shorter and add examples");
// Session remembers previous messages

campaignOpsApi - Campaign Operations

graph - Computation Graph Control

log - Debug Logging

Other injected context

Deferred Computation

Cross-Campaign References

Scripts can access data from other campaigns using campaignOpsApi.externalKey(companyName, campaignName, "Phase/Step/Key"). This enables:

• Pulling reference data from a "master data" campaign
• Comparing results across campaigns
• Building aggregation scripts that read from multiple sources

Async Computation with Callbacks

Scripts can trigger computations and receive a callback when they complete:

campaignOpsApi.updateCampaignKeysAndCompute(
    campaignId,
    {"Phase/Step/headline": "New headline value"},
    "Phase/Step/final_document",   // compute up to this path
    function(status) {
        if (status === "SUCCESS") log.info("Downstream computed!");
        if (status === "ERROR") log.error("Computation failed");
    },
    "Updated headline and recomputed"
);

4. Variable Type Options (CC Item Configuration)

Each CC item type has a hidden configuration object (options) that controls its behavior. These options aren't always visible in the UI but fundamentally change how the variable works.

Prompt Variables (prompt, json_prompt, image_prompt)

json_prompt adds: jsonSchemaKey - env var key for JSON Schema v4 that constrains AI output.

image_prompt adds: imageUrl - URL of an image for vision model analysis (png, jpg, gif, webp).

Session Prompt (session_prompt)

DALL-E Image Generation (dalle)

Asset Generation (asset)

Web Scraper (web_scraper)

Function (function)

File Content (file_content)

5. Prompt Post-Processing & AI Patching

Post-Processing Chain

After a prompt variable produces its initial result, post-processing can apply a chain of additional LLM prompts to refine it:

flowchart TD
    Initial["Initial LLM result"] --> PP1["Post-processing prompt 1
(e.g., improve grammar)"]
    PP1 --> PP2["Post-processing prompt 2
(e.g., summarize)"]
    PP2 --> Final["Final result stored"]

    Initial -.->|"Available as ${0}"| PP1
    PP1 -.->|"Available as ${1}"| PP2

Each post-processing step can reference:

Previous results in the chain are available as ${0}, ${1}, etc. This enables multi-stage refinement pipelines.

AI Patching (Semantic Merge)

When a prompt variable has resultType = PATCHED, the system performs a two-step AI merge:

1. Compute Patch - AI analyzes the semantic difference between the original result and the user's override:

   Prompt: "What changed between: [original] and: [override]?"
   Result stored in: item.patch

2. Apply Patch - AI merges the original with the semantic patch to create a final version:

   Prompt: "Starting with: [original], apply this change: [patch]"
   Result stored in: item.patched

The patching prompts are loaded from environment variables:

• {key}-ComputePatch (key-specific) or ComputePatch (global fallback)
• {key}-ComputePatchedContent (key-specific) or ComputePatchedContent (global fallback)