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 |
| 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
umask 077
cp .env.example .env
cp env/console.env.example env/console.env
cp env/portal.env.example env/portal.env
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 (full stack: API + both BFFs + both SPAs + form-builder). Portal RP secrets live in env/portal.env.
To start only the public portal (API already running):
The portal UI is at https://localhost:7073. pnpm dev:https already starts it; pnpm dev:portal is the subset when the API is up. Use pnpm dev:portal:http for plaintext.
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 (included in the full stack) / pnpm dev:console:web:https |
Served behind Caddy HTTPS | script-controlled |
Portal frontend (packages/portal-web) |
pnpm dev:https (included) / pnpm dev:portal / pnpm dev:portal:web:https |
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: included in pnpm dev:https; host Node via pnpm dev:portal (SERVER_CERT/SERVER_KEY) |
Internal HTTPS, CA-verified by Caddy | launcher injects cert PEMs; secrets in env/portal.env |
| Console BFF | HTTPS preferred: included in pnpm dev:https; host Node via pnpm dev:console |
Internal HTTPS, CA-verified by Caddy | launcher injects cert PEMs; secrets in env/console.env |
| Portal BFF upstream to API | Must match API scheme | http://server:7070 |
FLOH_INTERNAL_URL |
| Console BFF upstream to API | Host: {FLOH_INTERNAL_URL}/api; docker runtime: BFF_PROXY_TARGET |
http://server:7070 |
FLOH_INTERNAL_URL / docker BFF_PROXY_TARGET |
| OIDC callback URL | Match console BFF origin (/bff/callback) |
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