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

Communication with ServiceNow uses three APIs:

• Table API — reads flow data (GET on sys_hub_* tables), creates records (POST/PUT)
• GraphQL API — incremental updates via flowPatch mutations (insert, update, delete steps)
• ProcessFlow API — publishes flows (snapshot creation + compilation), fallback values

Authentication supports OAuth2 (Client Credentials) or Basic Auth. Rate-limited requests (HTTP 429) are retried with backoff.

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.