Floh Workflow Engine¶

A multi-step workflow orchestration platform built with Fastify, Angular, and Kysely.

Product overview. For a high-level, print-friendly tour of the platform — the design / route / deliver / prove pillars, capability grid, step-type catalog, security model, and integrations — see the Floh product overview slick sheet (HTML, 5 pages).

Features¶

Multi-step Workflows — define workflows with action, approval, notification, connector, and condition steps
OIDC Authentication — integrates with any OIDC-compliant identity provider
Role-Based Access Control — admin, approver, resource manager, and requestor roles with granular permissions
Email Notifications — Handlebars-based email templates with SMTP integration
Approval Workflows — single, sequential, and parallel approval patterns with escalation
Scheduled Workflows — cron-based triggers via BullMQ
Custom Connectors — extensible connector framework with built-in HTTP and delay connectors
Audit Logging — immutable, append-only audit trail for all actions
Dual Database Support — MySQL or PostgreSQL via Kysely
Management UI — Angular + PrimeNG dashboard with workflow designer, task inbox, reports
Public Portal — firewall-friendly portal for external users to handle invitations, tasks, and approvals

Tech Stack¶

Layer	Technology
Backend	Fastify 5, TypeScript, Kysely, BullMQ
Frontend	Angular 21, PrimeNG, PrimeFlex
Database	PostgreSQL 16 or MySQL 8
Queue	Redis 7 + BullMQ
Auth	OIDC (any provider), JWT
Email	Nodemailer + Handlebars
Testing	Vitest, Jest, Playwright
Deployment	Docker, Docker Compose

Quick Start¶

# Prerequisites: Node.js 24+, pnpm, Docker

# Clone and install
git clone <repo-url> floh && cd floh
pnpm install

# Start infrastructure
docker compose -f docker/docker-compose.yml up -d postgres redis mailhog

# Run migrations
pnpm migrate:latest

# Preferred: HTTPS local dev (certs + TLS_* / NODE_EXTRA_CA_CERTS — see getting-started/dev-quickstart.md)
pnpm dev:https

# HTTP-only: pnpm dev

The API is at https://localhost:7070 (docs at /api/docs) with TLS enabled; use http://localhost:7070 only for HTTP-only dev.

The admin UI is at https://localhost:7072 with pnpm dev:https.

To also start the public portal (with the API already running):

pnpm dev:portal:https

The portal UI is at https://localhost:7073. With pnpm dev:portal:https and TLS in .env, the portal BFF serves https://localhost:7071 (PORTAL_LISTEN_TLS=true is set by that script). For HTTP-only, use pnpm dev:portal (http://localhost:7071, no PORTAL_LISTEN_TLS).

TLS Checklist (All Tiers)¶

Tier	Local dev	CI/AWS deploy	Primary settings
Edge / ingress	n/a	HTTPS terminated by Caddy (`:443`)	`DEPLOY_DOMAIN`, `DEPLOY_PORTAL_DOMAIN`
API server (`packages/server`)	HTTPS preferred (`TLS_CERT_FILE`, `TLS_KEY_FILE`); HTTP if unset	Internal HTTP behind Caddy	`TLS_CERT_FILE`, `TLS_KEY_FILE` (local only)
Node trust store (portal-bff/scripts/tests)	Needed for self-signed local HTTPS	n/a	`NODE_EXTRA_CA_CERTS`
Admin frontend (`packages/web`)	`pnpm dev:https` for HTTPS UI	Served behind Caddy HTTPS	script-controlled
Portal frontend (`packages/portal-web`)	`pnpm dev:portal:https` for HTTPS UI	Served behind Caddy HTTPS	script-controlled
Form-builder (`packages/form-builder-app`)	`pnpm dev:form-builder` (HTTPS by default; `:http` opt-out)	Served behind Caddy HTTPS	script-controlled
Portal BFF (`packages/portal-bff`)	HTTPS preferred: `PORTAL_LISTEN_TLS` + `TLS_*` (via `pnpm dev:portal:https`)	Internal HTTP behind Caddy	`PORTAL_LISTEN_TLS`, `TLS_CERT_FILE`, `TLS_KEY_FILE`
Portal BFF upstream to API	Must match API scheme	`http://server:7070`	`FLOH_INTERNAL_URL`
OIDC callback URL	Match API scheme/host	HTTPS public domain	`OIDC_REDIRECT_URI`
OIDC post-logout redirects	`https://localhost:7072`, `https://localhost:7073` (plus any local HTTP origins in use)	`https://floh.authilize.com`, `https://myfloh.authilize.com`	IdP client configuration

See detailed setup in:

Documentation Sections¶

Section	Description
Getting Started	Setup, prerequisites, and development workflow
Architecture	System context, package map, request flows, and design decisions
User Guide	Using the workflow engine, admin settings, and reporting
Connectors	Creating, managing, and testing connectors
Workflows	Workflow lifecycle, parallel branches, and examples
Portal	Public portal architecture, organizations, and user profiles
Security	CORS, CSRF, secrets, encryption, RBAC, and audit logging
Integration	API reference, AI integration, and MCP setup
Operations	Deployment, worker configuration, and operational runbook

Project Structure¶

floh/
├── packages/
│   ├── server/       # Fastify backend API
│   ├── web/          # Angular frontend (admin)
│   ├── portal-bff/   # Portal Backend-for-Frontend (stateless proxy)
│   ├── portal-web/   # Portal Angular frontend (external users)
│   └── shared/       # Shared TypeScript types
├── docker/           # Docker and compose files
└── docs/             # Documentation