Architecture

High-level overview of how letitflow-sn works.

Components

Go Server

The server provides:

• REST API — endpoints for create, update, export, validate, and diagram generation
• Web UI — embedded frontend (landing page, flows browser, YAML editor)
• Docs — embedded documentation site at /docs
• Session management — stores SN credentials in server-side sessions (never sent to the browser)

ServiceNow Integration

All communication with ServiceNow happens through the standard REST Table API. The tool:

• Reads flow data via GET queries on sys_hub_* tables
• Creates and updates records via POST and PUT on those tables
• Handles authentication (OAuth2 or Basic Auth)
• Retries on rate limits (HTTP 429)

Data Flow

Read / Export

1. Fetch — parallel API calls collect flow records, steps, triggers, variables
2. Build — raw records are assembled into a domain model (step tree, data pills, values)
3. Convert — the domain model is translated to the YAML schema format

Create

1. Parse — YAML is parsed into schema types
2. Validate — structural checks, pill reference validation
3. Resolve — pill references are resolved, UUIDs assigned to steps
4. Create — records are created in ServiceNow (flow, trigger, steps, variables)
5. Publish — if status: published, the flow is compiled and activated

Update

1. Parse — updated YAML is parsed
2. Fetch — current flow state is fetched from ServiceNow
3. Diff — structural comparison produces a patch (inserts, updates, deletes, reorders)
4. Apply — changes are applied incrementally to the live flow

Web UI Architecture

The frontend is a multi-page static site (not a SPA framework) built with:

• TypeScript for all interactivity
• Monaco Editor for YAML editing with autocompletion
• Tailwind CSS for styling
• Vite for bundling

The Go server embeds the built frontend assets and serves them alongside the API.