Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cloudify.biz/llms.txt

Use this file to discover all available pages before exploring further.

This page goes deep on the mechanics. If you’re looking for an overview of what Lighthouse AI does and who it’s for, start with What is Lighthouse AI?.

​
A Session, Not a Form

Most integration tools ask you to configure fields, select triggers, and wire up connectors manually. Lighthouse AI works differently you open a session, describe what you need, and the system takes it from there. A session is a single, continuous run through the four-agent pipeline. Each agent picks up where the last one finished. Nothing is handed off manually. Nothing falls between the cracks. Here is exactly what happens inside that session.

​
Stage 1 — Inside the Onboarding Agent

The Onboarding Agent is the most consequential part of the pipeline. What it produces determines the quality of everything that follows.

​
How it thinks about your integration

Most AI tools ask generic questions. The Onboarding Agent does the opposite — it has deep knowledge of how real business applications are structured, and uses that to ask precise, relevant questions from the moment you describe your integration. When you say “connect HubSpot to QuickBooks,” it already knows:
  • HubSpot’s deal object structure, pipeline stages, and available webhooks
  • QuickBooks’ invoice schema, required fields, and currency format expectations
  • The most common failure points between these two systems
It uses that knowledge to surface questions you may not have thought to ask:
“Should we create invoices for all closed-won deals, or only those above a certain value?” “How should we handle deals with multiple line items — one consolidated invoice, or one per item?” “If a contact exists in HubSpot but not in QuickBooks — do we create it, skip the sync, or raise an alert?”
These are not prompts from a template. They are the questions an experienced integration engineer would ask before writing a single line of code.

​
What the Onboarding Agent produces

By the end of Stage 1, the agent has produced a complete integration specification — the source of truth for every stage that follows.

API Connection Map

Every endpoint involved — what gets called, in what order, with what authentication method, and what response is expected.

Entity Relationship Map

How data objects in System A correspond to data objects in System B, field by field — including type conversions and format differences.

Trigger & Condition Registry

Every event that starts the workflow, plus every condition or exception that should change the behaviour or skip a run entirely.

Edge Case Register

Known failure scenarios, null value rules, deduplication logic, and data mismatch strategies — documented before the Coding Agent begins.
The Edge Case Register is what separates Lighthouse AI from generic vibe coding tools. Most tools write the happy path and leave edge cases for production to discover. The Onboarding Agent forces those decisions before code is written.

​
Stage 2 — Inside the Coding Agent

The Coding Agent receives the full specification from the Onboarding Agent and begins building. You can watch this happen in real time inside the session.

​
What gets written

The Coding Agent produces TypeScript — not visual flow diagrams, not drag-and-drop blocks, not low-code configuration files. Actual typed code that your engineering team can read, reason about, and modify. Each integration is made up of several files with clear, separated responsibilities:
The core logic file. Contains the trigger listener, data transformation, API calls, conditional routing, and error handling — shaped to your specific workflow and business rules.
hubspot-quickbooks.ts
// HubSpot → QuickBooks integration handler
// Generated from: Onboarding spec v1 | Session ID: lh_xk291
import { HubSpotClient } from '@hubspot/api-client';
import { QuickBooksClient } from './clients/quickbooks';
import { mapDealToInvoice } from './mappers/deal-invoice';
import { handleCurrencyMismatch } from './handlers/currency';

export async function onDealClosedWon(dealId: string) {
  const deal = await hubspot.crm.deals.basicApi.getById(dealId);

  // Business rule: skip deals below minimum threshold
  if (deal.properties.amount < config.minimumDealValue) return;

  const invoice = mapDealToInvoice(deal);
  await handleCurrencyMismatch(invoice, deal);
  await quickbooks.invoice.create(invoice);
}

​
What the Coding Agent does not do

The Coding Agent does not generate a generic template and fill in variable names. Every conditional rule, business exception, and data mapping defined during onboarding is present in the code from the first version — not added as an afterthought.

​
Stage 3 — Inside the Testing Agent

Once the Coding Agent finishes, the Testing Agent runs automatically. It does not wait for you to configure test cases — it generates them from the integration specification produced in Stage 1.

​
How test cases are generated

The Testing Agent cross-references three sources to build its test suite:
  1. The Onboarding Spec — every trigger, condition, and edge case registered in Stage 1 becomes a named test scenario
  2. Real data shapes from your connected apps — the agent analyses actual field structures to construct realistic test payloads, not mocked placeholder values
  3. Known failure patterns — a library of integration failure modes specific to the platforms involved (currency mismatches, duplicate records, rate limit behaviour, null field handling)

​
What a test run looks like

Testing Agent — Running test suite
hubspot-quickbooks.test.ts | 6 tests | TypeScript

TEST RESULTS

✅  PASS   Creates invoice from a valid closed-won deal
✅  PASS   Handles null amount field gracefully (defaults to 0)
✅  PASS   Skips deals below minimum value threshold
✅  PASS   Expands multi-line-item deals into separate invoice lines
✅  PASS   Deduplicates: skips invoice if deal ID already processed
❌  FAIL   Currency mismatch between HubSpot deal (USD) and QuickBooks
           customer default (GBP) — no fallback rule defined

​
What happens when a test fails

A failed test does not stop the session — it surfaces the failure with a precise explanation and prompts you to define the missing rule in plain language. You respond, the Onboarding Agent updates the spec, the Coding Agent patches the relevant file, and the Testing Agent re-runs the affected scenarios.
Deployment is blocked until all tests pass. A failure here costs nothing. A failure in production costs data integrity, engineering time, and trust.
This loop — surface failure, define rule, patch code, re-test — continues until the suite is clean. Only then does the session advance to Stage 4.

​
Stage 4 — Inside the Deployment Agent

The Deployment Agent does not simply push code to a server. It prepares a complete, production-grade package and hands it off to your team with full documentation.

​
What gets configured

1

CI/CD Pipeline

A GitHub Actions workflow is generated and committed to your repository. Every future change to the integration triggers an automated cycle — install, test, deploy — without manual intervention.
.github/workflows/deploy.yml
name: Deploy Lighthouse Integration
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run integration tests
        run: npm test
      - name: Deploy to Lighthouse Engine
        run: npx sst deploy --stage production
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
2

Secrets Management

All credentials and tokens are moved to AWS SSM Parameter Store. They are never stored in committed files or plain environment variables. The integration references them by path at runtime.
HubSpot access token → SSM Parameter Store
QuickBooks OAuth credentials → SSM Parameter Store
Webhook signing secrets → SSM Parameter Store
3

Runtime Registration

The integration is registered with the Lighthouse Engine — the runtime environment that manages uptime, webhook ingestion, retries, and structured logging from the moment your integration goes live.
4

Handoff Report

A HANDOFF.md is generated and committed alongside the code. It documents what the integration does in plain language, every system involved and how they authenticate, where all secrets are stored, and the test results from Stage 3.This file exists for your engineering team — so they can understand, support, and extend the integration without reverse-engineering the code.

​
After Deployment — The Lighthouse Engine

Once your integration is live, the Lighthouse Engine manages everything at runtime. This is the layer that makes Lighthouse AI integrations behave differently from scripts that pass local tests but fail silently in production.

Webhook Manager

Ingests, validates, and queues payloads from third-party systems. Handles signature verification and deduplication before your integration logic ever runs.

Structured Logging

Every run is logged — payload received, each step executed, result recorded. Searchable by run ID, timestamp, or status. No silent failures.

Automatic Retries

If a downstream API is temporarily unavailable, the Engine retries on a configurable backoff schedule. Recovery is handled automatically.

One-Click Replay

Any failed run can be replayed with its original payload. No need to wait for the triggering event to happen again.

Event-Driven Processing

Runs are processed asynchronously. High event volumes do not block or slow each other — every run executes independently.

Condition-Based Routing

If your workflow branches at runtime — different paths for different record types, values, or states — the Engine handles routing logic without additional code.

​
How Agent Handoffs Work

The pipeline is sequential, but handoffs are automatic. You do not manually advance between stages — the session manages it. 
You describe your integration
          ↓
Onboarding Agent builds the specification
          ↓  Spec passed to Coding Agent automatically
Coding Agent writes the integration files
          ↓  Files passed to Testing Agent automatically
Testing Agent runs the full test suite
          ↓
     ┌────┴────┐
   PASS      FAIL
     ↓          ↓
Deployment   Session surfaces failure with explanation
Agent begins  ↓
             You define the missing rule in plain language
             ↓  Spec updated → Code patched → Tests re-run
             ↓  Loop continues until all tests pass
             ↓
        Deployment Agent begins
          ↓
Integration registered with Lighthouse Engine
          ↓
Integration is live
You can pause the session at any handoff point. If you want to review the full specification before code is generated, pause after Stage 1, read through the spec, and make adjustments. The agents resume from exactly where you stopped.

​
Code Ownership and Portability

Every file generated by Lighthouse AI belongs to you and lives in your repository.
Every file the Coding Agent produces is committed directly to your repo:
  • Integration handler (*.ts)
  • Field mappers (mappers/*.ts)
  • Error handlers (handlers/*.ts)
  • Test suite (*.test.ts)
  • CI/CD pipeline (.github/workflows/deploy.yml)
  • Environment config reference (.env.production)
  • Handoff documentation (HANDOFF.md)
You can clone, read, and audit every line.
Yes. The generated code is standard TypeScript following conventional patterns. Engineers can add logic, extend handlers, refactor structure, or integrate the files into a larger codebase. There is no proprietary wrapper preventing modification.One recommendation: run the test suite after any modification before deploying, to verify nothing in the existing logic has been broken.
The code continues to work. The Lighthouse Engine handles runtime, but the integration logic itself is standard TypeScript deployable to any compatible environment. There is no lock-in at the code layer — only at the runtime layer if you choose to use the Engine.
Yes. All files use standard patterns with inline comments. Secrets are stored externally and referenced by path — no credentials appear in source code or logs. The HANDOFF.md provides a plain-language audit trail for non-technical reviewers.

​
Security Model

OAuth Where Available

Platform connections use OAuth by default. Lighthouse AI requests only the minimum permission scopes required for the integration — nothing broader.

Secrets Never in Code

All credentials are stored in AWS SSM Parameter Store from the first deployment. They are never written into files, environment variables, or logs.

Payload Validation

Every incoming webhook is verified against its signing secret before your integration logic executes. Invalid or tampered payloads are rejected at the Engine layer.

Isolated Run Execution

Each integration run executes in an isolated context. A failure or error in one run cannot affect concurrent runs of the same or a different integration.

​
Continue

Quickstart

Build and deploy your first integration step by step.

Browse Templates

Pre-built integrations for common workflows, ready to customise.

Supported Connectors

Every app and API Lighthouse AI can connect to out of the box.

Talk to the Team

Complex use case? We’ll scope it with you before you start.