Developer — LedgerFlow

API-First

Your Schema Is the API

LedgerFlow is PostgREST-fronted: the moment a table, view, or function lands in the api schema it becomes a REST endpoint — described by OpenAPI, secured by JWT, and enforced by row-level security in the database itself.

Auto-Generated REST

~130 views and ~90 functions in the api schema are exposed as REST endpoints automatically via PostgREST. No hand-written controllers, no drift between docs and reality.

Dual Connection Pools

A default pool for general traffic, a dedicated fast pool routed to /rpc/transactions*, and a read-replica pool for reporting. NGINX routes between them transparently.

OpenAPI & Swagger

Every endpoint is self-documenting through an interactive Swagger UI — explore, authenticate, and call the API straight from the browser.

JWT & OIDC Auth

Bearer-token auth with OIDC/Keycloak SSO. Roles map to PostgreSQL roles, so authorisation is enforced by the database — not bolted on in middleware.

Webhooks Without a Broker

A rule firing a queue event posts straight to pgmq and is delivered by a Go worker with templating and exponential-backoff retry. Real-time callbacks, no polling, no Kafka.

Snowflake IDs

64-bit, time-ordered, coordinator-free identifiers with 300B+ capacity. Always handle them as strings end-to-end so no precision is lost in JSON.

MCP for Coding Agents

Point Your Agent
at the Ledger

LedgerFlow ships a public, JWT/OAuth-secured Model Context Protocol server. Connect Claude Desktop, VS Code, or Claude Code and let your coding agent read against a real deployment while it builds your integration.

A Server Your Agent Connects To

A dedicated MCP endpoint (separate from the API) that exposes LedgerFlow over the protocol coding agents already speak — discovery, tools, and resources out of the box.

A Curated, Read-Only Toolset

A safety-reviewed allowlist of read tools plus knowledge-base search. Admin and mutating operations are excluded at dispatch, so an agent can explore but never write.

OAuth 2.1 & Scoped Tokens

OAuth for desktop clients, or mint a scoped, time-limited token from the in-app Setup → Agent & MCP page. Every call is rate-limited and size-capped to protect the model's context.

Grounded in Your Own Data

Tools resolve against your deployment over the read pool, and a retrieval layer answers product questions from the documentation corpus — so answers are specific to your install.

Self-Hosting & Deploy

One Compose File.
Your Infrastructure.

LedgerFlow runs as a self-contained stack of orchestrated services. No managed dependencies you can't see, and no data leaving your perimeter unless you choose to send it.

17 Services, One Stack

Database, dual API, UI, Go workers, reverse proxy, and a full observability suite orchestrated by a single Docker Compose file. Bring your own infrastructure.

PostgreSQL-Native

pgmq replaces an external message broker; pg_timetable replaces an external scheduler. Fewer moving parts, one source of truth, no Kafka/RabbitMQ/cron to operate.

Ring-Fenced per Tenant

Each customer is a fully isolated stack with its own database. The database boundary is the tenant boundary — nothing is shared, nothing leaks across deployments.

Observability Included

Grafana, Prometheus, Loki, Tempo, and Pyroscope ship wired up over OpenTelemetry — metrics, logs, traces, and continuous profiling from the first compose up.

Architecture & Stack

A Stack You Can Reason About

ledgerflow-stack.txt

# Data + API tier
PostgreSQL 18   pgmq · pg_partman · pgvector · snowflake · pg_timetable
PostgREST      default + fast (txn) + read-replica pools
NGINX          routing, rate limiting, native OpenTelemetry

# Application tier
SQLPage        SQL-driven operator UI (148+ pages)
Go 1.25 workers HTTP · SMTP · WebSocket · DB-task queue processors
MCP servers    internal + public (JWT / OAuth)

# Observability tier
Grafana · Prometheus · Loki · Tempo · Pyroscope · Alloy (OTel)

# Identifiers — no central coordinator
Snowflake 64-bit IDs time-ordered · 300B+ capacity · partition-friendly