flowcatalyst-go

module

v0.0.0-...-e3c07e6 Latest Latest Go to latest Published: Oct 27, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/flowcatalyst/flowcatalyst-go

Links

Open Source Insights

README ¶

FlowCatalyst

A multi-tenant event router and webhook delivery platform, written in Go.

Applications publish domain events. Other applications (or yours, or external services) consume them via webhook subscriptions. FlowCatalyst handles routing, FIFO ordering, retry, rate-limiting, circuit breaking, and audit — across multiple tenants — so you don't have to reimplement that machinery in every consumer.

The Postgres schema, HTTP API contracts, OpenAPI spec, and Vue frontend are stable: existing SDK consumers and webhook subscribers keep working unchanged across releases.

Architecture at a glance

┌───────────────────┐                          ┌──────────────────────┐
│ Consumer apps     │  ──── events ──────▶     │   FlowCatalyst       │
│ (SDK / outbox)    │                          │                      │
│                   │  ◀──── webhooks ────     │   Platform · Router  │
└───────────────────┘                          │   Scheduler · Stream │
                                                │   Outbox             │
                                                └──┬───────────┬───────┘
                                                   │           │
                                                   ▼           ▼
                                              PostgreSQL    SQS FIFO
                                                   │           │
                                                   ▼           ▼
                                                Redis       Customer IDPs
                                              (HA leader)  (OIDC bridge)

In local development everything above collapses into a single fcdev process backed by an embedded Postgres — no Docker, no SQS, no Redis. (The embedded Postgres is vanilla; to add PostGIS see docs/embedded-postgres-postgis.md.)

Quick start

As a developer publishing events

# 1. Install fcdev (the local development binary)
curl -fsSL https://raw.githubusercontent.com/flowcatalyst/flowcatalyst/main/install.sh | sh

# 2. Run it
fcdev

# 3. Open http://localhost:8080

Windows (PowerShell 5.1+):

irm https://raw.githubusercontent.com/flowcatalyst/flowcatalyst/main/install.ps1 | iex

See Installing fcdev for pinning versions, manual installs, checksum/signature verification, and self-update.

As an operator deploying production

Deploy fc-server (the unified binary) with the subsystems you need enabled via env vars — run one instance with everything on, or several instances each running a subset (router-only, stream-only, …) for split topologies. See Operator notes.

As an engineer working on FlowCatalyst itself

Read docs/architecture.md, then CONVENTIONS.md before writing any code. The docs/usecase-pattern.md walks the compile-time-sealed UseCase + UnitOfWork pattern with a worked example.

Installing fcdev

fcdev is the all-in-one local-development binary. It ships pre-built for macOS (Apple Silicon + Intel), Linux (x86_64 + arm64), and Windows (x86_64). The install commands below fetch the latest release from GitHub, verify it, and put it on your PATH.

Release assets are named with Go's GOOS-GOARCH convention (darwin-arm64, darwin-amd64, linux-amd64, linux-arm64, windows-amd64).

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/flowcatalyst/flowcatalyst/main/install.sh | sh

The script detects your OS/arch from uname, downloads the matching archive, verifies its SHA256 sidecar, installs to /usr/local/bin/fcdev if writable (else ~/.local/bin/fcdev — no sudo prompt), and on macOS strips the Gatekeeper quarantine attribute.

Windows

irm https://raw.githubusercontent.com/flowcatalyst/flowcatalyst/main/install.ps1 | iex

Downloads the windows-amd64 zip, verifies its SHA256, extracts to %LOCALAPPDATA%\Programs\fcdev, and adds that directory to your user PATH (re-open your terminal afterwards). Windows-on-ARM runs the x64 binary under emulation.

Upgrading

Once fcdev is on your PATH, it self-updates — no need to re-run the installer:

fcdev upgrade           # download & replace if a newer release exists
fcdev upgrade --check   # just check, don't install
fcdev upgrade --force   # re-install even if already current

upgrade uses the same release artifacts the installer scripts do, verifies the SHA256, and atomically replaces the running binary.

Environment variables

Both installer scripts honour the same three variables:

Variable	Default	Purpose
`FC_DEV_VERSION`	latest stable	Pin a specific version (e.g. `0.5.0`). The leading `v` is optional.
`FC_DEV_INSTALL_DIR`	platform default (see above)	Where to write `fcdev`.
`FC_DEV_FORCE`	`0`	When `1`, reinstall even if the requested version is already present.

Example — pin a version into ~/bin on Linux:

curl -fsSL https://raw.githubusercontent.com/flowcatalyst/flowcatalyst/main/install.sh \
  | FC_DEV_VERSION=0.5.0 FC_DEV_INSTALL_DIR="$HOME/bin" sh

Manual install

If you'd rather not pipe a remote script into your shell, every archive on the releases page ships a .sha256 sidecar:

# 1. Pick your target (Go GOOS-GOARCH)
TARGET=darwin-arm64        # macOS Apple Silicon
# TARGET=darwin-amd64      # macOS Intel
# TARGET=linux-amd64       # Linux x86_64
# TARGET=linux-arm64       # Linux ARM64
# TARGET=windows-amd64     # Windows (use the .zip variant)

VERSION=0.5.0

# 2. Download archive + checksum
base="https://github.com/flowcatalyst/flowcatalyst/releases/download/fcdev/v${VERSION}"
curl -LO "${base}/fcdev-v${VERSION}-${TARGET}.tar.gz"
curl -LO "${base}/fcdev-v${VERSION}-${TARGET}.tar.gz.sha256"

# 3. Verify
shasum -a 256 -c "fcdev-v${VERSION}-${TARGET}.tar.gz.sha256"

# 4. Extract + install
tar -xzf "fcdev-v${VERSION}-${TARGET}.tar.gz"
sudo install -m 0755 "fcdev-v${VERSION}-${TARGET}/fcdev" /usr/local/bin/

# 5. (macOS only) strip Gatekeeper quarantine
xattr -d com.apple.quarantine /usr/local/bin/fcdev 2>/dev/null || true

fcdev version

On a private checkout or rate-limited network you can use the GitHub CLI instead, which reuses your gh auth:

gh release download fcdev/v0.5.0 --repo flowcatalyst/flowcatalyst \
  --pattern 'fcdev-v0.5.0-darwin-arm64.tar.gz*'

Verifying Linux archives (optional)

Linux release archives are additionally signed via Sigstore cosign keyless — the signature is bound to the exact GitHub Actions run that built it, recorded in the public Rekor transparency log:

cosign verify-blob \
  --signature  "fcdev-v${VERSION}-${TARGET}.tar.gz.sig" \
  --certificate "fcdev-v${VERSION}-${TARGET}.tar.gz.pem" \
  --certificate-identity-regexp '^https://github.com/flowcatalyst/flowcatalyst(-go)?/\.github/workflows/release-fcdev\.yml@refs/tags/fcdev/v' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  "fcdev-v${VERSION}-${TARGET}.tar.gz"

Each release's notes include the exact --certificate-identity-regexp for that build. macOS and Windows archives are not yet codesigned.

Troubleshooting

fcdev: command not found after install — the install dir isn't on your PATH yet. Open a new terminal, or source ~/.zshrc (the script prints the exact line to add).
macOS "cannot be opened because it is from an unidentified developer" — the installer strips the quarantine xattr automatically; for a manual download run xattr -d com.apple.quarantine /usr/local/bin/fcdev.
First run downloads Postgres — fcdev fetches a platform-specific embedded-Postgres bundle on first launch, so the initial start needs network access and is slower than subsequent runs.

Binaries

Binary	Purpose
`fc-server`	Unified production server — every subsystem (platform API, router, scheduler, stream, outbox, MCP) toggleable via env vars. Run one instance with everything on, or several each running a subset for split topologies.
`fcdev`	Local development monolith: all subsystems in one process against an embedded Postgres.

The repo ships these two binaries rather than a separate executable per subsystem — split topologies are achieved by running multiple fc-server instances with different subsystems enabled.

Building from source

The repo builds with make (run make help for the full target list):

make build            # build the Vue frontend, then every Go binary into bin/
make build-release    # optimized build (trimpath, -s -w)
make go-build         # Go binaries only (assumes frontend/dist already built)

Local dev loop (embedded Postgres — no Docker, no separate migrate step):

make run              # run fcdev once
make dev              # run fcdev with live reload (requires air; see `make install-tools`)
make dev-full         # fcdev + the Vite frontend dev server together
make run-server       # run the unified fc-server (subsystems via env)

Bootstrap & database:

make setup            # bootstrap admin user + default tenant + .env, then print next steps
make init             # bootstrap only
make fresh            # truncate every FlowCatalyst table (keeps schema)
make db-reset         # wipe the embedded Postgres data dir and start fresh

fcdev init also creates your application and writes its service-account credentials to .env. Those credentials are provisioned exactly like an application service account made in the admin UI: they carry the platform:application-service role and are confined to that one application. Event types you publish must therefore start with <application-code>: (anything else is rejected with 400), and event types are registered through the SDK sync endpoint (POST /api/applications/{appCode}/event-types/sync) rather than POST /api/event-types, which needs admin event-type permissions the application role does not carry.

Quality gates:

make install-hooks    # once: git pre-push hook that runs `make pre-push`
make pre-push         # fast gate (~1 min, no Docker): build, vet, pinned lint, conformance, changed-package tests
make test             # unit + integration (embedded Postgres)
make lint             # pinned golangci-lint (built into ./.tools with your Go)
make ci               # everything CI runs, same order, same pinned tools

See docs/contributing.md ("Before you push").

SDK clients

Language	Location
TypeScript / JavaScript	`clients/typescript-sdk/`
Laravel / PHP	`clients/laravel-sdk/`
Go (in-repo package)	`pkg/fcsdk/`

The TS and Laravel SDKs are generated from the huma OpenAPI spec (make sdk-generate); releases are cut with make release-ts-sdk / make release-laravel-sdk and mirrored to standalone repos. All SDKs cover the outbox pattern for atomic event publishing, definition syncing for declaring event types and roles, and webhook signature verification.

Technology stack

Layer	Technology
Language	Go 1.27
HTTP router	go-chi/chi v5
API / OpenAPI	huma v2 (OpenAPI 3.1, generated spec)
Database	PostgreSQL via pgx v5; handwritten SQL compiled with sqlc; goose migrations
Embedded DB (dev)	fergusstrange/embedded-postgres
Queue	AWS SQS FIFO (prod), embedded Postgres (dev); NATS supported
Auth	RS256 JWT (golang-jwt + lestrrat-go/jwx), OIDC bridge (coreos/go-oidc), WebAuthn/passkeys (go-webauthn), Argon2id passwords, HMAC webhook signing
Caching / HA	in-process cache + Redis (go-redis) for leader election
Metrics	Prometheus (client_golang)
Scheduling	robfig/cron
Secrets	AWS Secrets Manager, encrypted files
CLI	spf13/cobra
MCP	modelcontextprotocol/go-sdk (read-only server for LLM clients)
Frontend	Vue SPA, built and embedded via `//go:embed`

PostgreSQL extensions: none required. Partitioning is managed in-process, the same code in dev and prod — no pg_partman or pg_cron.

Operator notes

Default HTTP port

fc-server defaults to FC_API_PORT=8080. Older deployments defaulted to 3000 — operators behind load-balancer rules that hard-code 3000 should set FC_API_PORT=3000 explicitly. The FC_API_PORT env var (or its legacy alias PORT) overrides the binary default.

Service	Default	Override env
Platform HTTP	`FC_API_PORT=8080`	`FC_API_PORT` / `PORT`
fcdev	`--api-port 8080`	`FC_API_PORT` / `--api-port`
Metrics	`FC_METRICS_PORT=9090`	`FC_METRICS_PORT`
MCP	`127.0.0.1:8090`	`FC_MCP_PORT` / `FC_MCP_BIND`

The complete environment-variable reference (every variable the server, subsystems, and fcdev read, with defaults and aliases) is in docs/environment-variables.md.

Documentation

docs/architecture.md — package layout and library choices
docs/contributing.md — before you push: make pre-push, make ci, pinned tools
CONVENTIONS.md — engineering conventions (read before writing code)
docs/usecase-pattern.md — the sealed UseCase + UnitOfWork pattern, worked example
docs/wire-contract.md — the HTTP wire contract and how it's enforced
docs/sqlc.md — sqlc workflow and conventions
docs/oidc-security-audit.md — OIDC implementation security review
docs/adr/ — architecture decision records

License

Component	License	Text
Platform (`cmd/`, `internal/`, and everything not listed below)	Apache-2.0	`LICENSE`, `NOTICE`
Go SDK (`pkg/fcsdk/`, its own Go module)	Apache-2.0	`pkg/fcsdk/LICENSE`, `pkg/fcsdk/NOTICE`

The platform and the Go SDK are permissively licensed so that anyone can run, modify and build on them without a legal review standing in the way; the Apache licence also carries an explicit patent grant. The Go SDK is a separate Go module (github.com/flowcatalyst/flowcatalyst/pkg/fcsdk) and carries its own copy of the licence and notice, because a module download contains only the module's own directory.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
bench
function-runtimes/wazerobench command Command wazerobench measures function artifacts on the platform's real function engine (internal/functions/engine, wazero) through the same runtimes.Loader the runner uses: a "wasm" artifact is compiled as is, a "js" artifact is a bundled script loaded into the shared QuickJS engine.	Command wazerobench measures function artifacts on the platform's real function engine (internal/functions/engine, wazero) through the same runtimes.Loader the runner uses: a "wasm" artifact is compiled as is, a "js" artifact is a bundled script loaded into the shared QuickJS engine.
function-runtimes/wazerobench/loopcfg command Command loopcfg isolates what wazero's CloseOnContextDone (the runner's deadline mechanism, engine.New) costs each guest: every workload, single thread, with the setting on (what the runner does) and off.	Command loopcfg isolates what wazero's CloseOnContextDone (the runner's deadline mechanism, engine.New) costs each guest: every workload, single thread, with the setting on (what the runner does) and off.
cmd
decrypt-check command Throwaway diagnostic: verify FLOWCATALYST_APP_KEY can decrypt a ciphertext (e.g.	Throwaway diagnostic: verify FLOWCATALYST_APP_KEY can decrypt a ciphertext (e.g.
fc-server command Command fc-server is the FlowCatalyst unified production server.	Command fc-server is the FlowCatalyst unified production server.
fcdev command Command fcdev is the FlowCatalyst developer monolith — a single binary that runs every subsystem against an embedded Postgres so engineers can iterate without Docker.	Command fcdev is the FlowCatalyst developer monolith — a single binary that runs every subsystem against an embedded Postgres so engineers can iterate without Docker.
fcrunner-echo command Command fcrunner-echo is the in-repo echo test runner (internal/functions/ echorunner): a Go v1 control-protocol client for the made-up runtime "echo".	Command fcrunner-echo is the in-repo echo test runner (internal/functions/ echorunner): a Go v1 control-protocol client for the made-up runtime "echo".
docs Package docs embeds the platform's PUBLISHED Markdown documentation — the curated set under published/ — so the running binary serves it to administrators (Platform → Documentation in the SPA, via /api/docs) and the pages always match the running build.	Package docs embeds the platform's PUBLISHED Markdown documentation — the curated set under published/ — so the running binary serves it to administrators (Platform → Documentation in the SPA, via /api/docs) and the pages always match the running build.
frontend Package frontend embeds the built Vue SPA (frontend/dist) into the Go binary and exposes it as an http.Handler.	Package frontend embeds the built Vue SPA (frontend/dist) into the Go binary and exposes it as an http.Handler.
internal
common Package common holds types shared across the router, queue, stream, outbox, and platform packages: messages, dispatch modes, mediation results, outbox status, configuration shapes, and warnings.	Package common holds types shared across the router, queue, stream, outbox, and platform packages: messages, dispatch modes, mediation results, outbox status, configuration shapes, and warnings.
envutil Package envutil holds the shared environment-variable parsing helpers the per-package FromEnv constructors use.	Package envutil holds the shared environment-variable parsing helpers the per-package FromEnv constructors use.
functions/abi Package abi is the function runner's guest calling convention, version 1 (docs/function-runner-plan.md §5): the frame layout both directions use, the request/response metadata, the host-call op codes and error codes, and the describe document a module declares its needs with.	Package abi is the function runner's guest calling convention, version 1 (docs/function-runner-plan.md §5): the frame layout both directions use, the request/response metadata, the host-call op codes and error codes, and the describe document a module declares its needs with.
functions/budget Package budget is the function runner's memory accounting (docs/function-runner-plan.md §7).	Package budget is the function runner's memory accounting (docs/function-runner-plan.md §7).
functions/control Package control is the wire contract between the platform and function runners (docs/function-runner-plan.md §8.3): the desired-state document a runner long-polls for, the heartbeat it reports back, and the emit request it makes on a function's behalf.	Package control is the wire contract between the platform and function runners (docs/function-runner-plan.md §8.3): the desired-state document a runner long-polls for, the heartbeat it reports back, and the emit request it makes on a function's behalf.
functions/echorunner Package echorunner is a tiny in-repo test runner that speaks the Go v1 control protocol for a made-up runtime, "echo".	Package echorunner is a tiny in-repo test runner that speaks the Go v1 control protocol for a made-up runtime, "echo".
functions/engine Package engine runs function modules on wazero (docs/function-runner-plan.md §6.1): one runtime per runner with a disk compilation cache, the `fc` host module every guest calls capabilities through, the load-time module check, and instances whose linear memory is charged to the runner's budget.	Package engine runs function modules on wazero (docs/function-runner-plan.md §6.1): one runtime per runner with a disk compilation cache, the `fc` host module every guest calls capabilities through, the load-time module check, and instances whose linear memory is charged to the runner's budget.
functions/fnfixture Package fnfixture is the raw ABI v1 guest the function runner's tests run: a Rust module (source in guest/) whose behaviour is chosen by the request path — /echo, /meta, /count, /spin, /grow?mb=N, /trap, /malformed and /call?op=N (the request body is passed to fc.call as a host-call frame).	Package fnfixture is the raw ABI v1 guest the function runner's tests run: a Rust module (source in guest/) whose behaviour is chosen by the request path — /echo, /meta, /count, /spin, /grow?mb=N, /trap, /malformed and /call?op=N (the request body is passed to fc.call as a host-call frame).
functions/jsengine Package jsengine embeds the function runner's shared JavaScript engine: QuickJS behind ABI v1, built from clients/fn-js-engine (see its build.sh).	Package jsengine embeds the function runner's shared JavaScript engine: QuickJS behind ABI v1, built from clients/fn-js-engine (see its build.sh).
functions/runner Package runner is the function runner (docs/function-runner-plan.md §6): it long-polls the platform for its pool's desired state, prepares the versions it names (download, verify, compile), routes HTTP invocations to them with per-endpoint auth and per-function permits, serves their host calls, and reports back in heartbeats.	Package runner is the function runner (docs/function-runner-plan.md §6): it long-polls the platform for its pool's desired state, prepares the versions it names (download, verify, compile), routes HTTP invocations to them with per-endpoint auth and per-function permits, serves their host calls, and reports back in heartbeats.
functions/runtimes Package runtimes turns a function artifact into something the engine can instantiate, for each runtime a version may declare:	Package runtimes turns a function artifact into something the engine can instantiate, for each runtime a version may declare:
ids Package ids holds distinct types for the platform's entity identifiers.	Package ids holds distinct types for the platform's entity identifiers.
logging Package logging configures structured logging via slog.	Package logging configures structured logging via slog.
mcp Package mcp implements the FlowCatalyst MCP (Model Context Protocol) server: read-only, agent-facing access to the platform's event types, subscriptions, applications, roles, and OpenAPI specs.	Package mcp implements the FlowCatalyst MCP (Model Context Protocol) server: read-only, agent-facing access to the platform's event types, subscriptions, applications, roles, and OpenAPI specs.
migrate Package migrate applies the embedded schema migrations to a Postgres database using github.com/pressly/goose/v3 as the runner.	Package migrate applies the embedded schema migrations to a Postgres database using github.com/pressly/goose/v3 as the runner.
netguard Package netguard keeps outbound deliveries away from addresses that should never be a customer webhook: the machine's own loopback, cloud metadata (169.254.169.254 and its IPv6 sibling), link-local ranges, and — unless allowed — private networks such as the cluster's own pod and service addresses.	Package netguard keeps outbound deliveries away from addresses that should never be a customer webhook: the machine's own loopback, cloud metadata (169.254.169.254 and its IPv6 sibling), link-local ranges, and — unless allowed — private networks such as the cluster's own pod and service addresses.
oauthtoken Package oauthtoken mints and caches OAuth2 client_credentials access tokens for one platform, for the components that call the platform as a client: the MCP server, and the router fetching its configuration document.	Package oauthtoken mints and caches OAuth2 client_credentials access tokens for one platform, for the components that call the platform as a client: the MCP server, and the router fetching its configuration document.
outbox Package outbox implements the outbox processor: it polls the consumer application's outbox table, batches by message group, and forwards to the FlowCatalyst platform API.	Package outbox implements the outbox processor: it polls the consumer application's outbox table, batches by message group, and forwards to the FlowCatalyst platform API.
outbox/mongo Package mongo is the MongoDB-backed outbox repository.	Package mongo is the MongoDB-backed outbox repository.
outbox/postgres Package postgres is the Postgres-backed outbox repository.	Package postgres is the Postgres-backed outbox repository.
outbox/sqlite Package sqlite is the SQLite-backed outbox repository.	Package sqlite is the SQLite-backed outbox repository.
platform/appdocs Package appdocs stores application-synced documentation: Markdown pages an application pushes through the SDK sync surface (POST /api/applications/{appCode}/docs/sync), read by administrators in Platform → Documentation.	Package appdocs stores application-synced documentation: Markdown pages an application pushes through the SDK sync surface (POST /api/applications/{appCode}/docs/sync), read by administrators in Platform → Documentation.
platform/application Package application represents a registered application (or integration) in the platform.	Package application represents a registered application (or integration) in the platform.
platform/application/api Package api wires the HTTP routes for the application subdomain via huma.	Package api wires the HTTP routes for the application subdomain via huma.
platform/application/operations
platform/appusers Package appusers is the user and invitation administration an application performs for its own users, as its own service account (F20).	Package appusers is the user and invitation administration an application performs for its own users, as its own service account (F20).
platform/audit Package audit holds the audit log entity and repository (read API + a direct batch-ingest Insert).	Package audit holds the audit log entity and repository (read API + a direct batch-ingest Insert).
platform/audit/api Package api wires the audit log read-only HTTP endpoints via huma.	Package api wires the audit log read-only HTTP endpoints via huma.
platform/auth Package auth houses:	Package auth houses: