Floh Workflow Engine¶
A multi-step workflow orchestration platform built with Fastify, Angular, and Kysely.
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
pnpm install
# Start infrastructure
docker compose -f docker/docker-compose.yml up -d postgres redis mailhog
# Run migrations
pnpm migrate:latest
# Start development servers
pnpm dev
The API is available at http://localhost:3000 (docs at /api/docs).
The UI is available at http://localhost:4200.
To also start the public portal:
The portal BFF runs at http://localhost:3001 and the portal UI at http://localhost:4201.
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