Skip to content

Commit 246b98e

Browse files
jumskijumski
committed
docs: redesign README with improved branding and feature descriptions (#428)
# Redesigned README with Enhanced Visual and Content Presentation This PR completely revamps the README to improve visual appeal and clarity of the project's value proposition. Key changes include: - Added a modern header with SVG logo, badges, and endorsement quote from Supabase CEO - Included an animated SVG diagram showing workflow execution with automatic retries - Restructured content to highlight key benefits and use cases more clearly - Added a quick start guide with code example showing the simplicity of workflow definitions - Improved package listing with version badges and links - Enhanced "Why pgflow?" section to better explain the problem being solved - Added comparison links to competing workflow solutions - Updated visual styling with better spacing and organization The new README provides a more compelling introduction to pgflow, making it immediately clear how it solves workflow orchestration challenges in Supabase projects.
1 parent 56748c7 commit 246b98e

File tree

4 files changed

+302
-58
lines changed

4 files changed

+302
-58
lines changed

‎README.md‎

Lines changed: 92 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,111 @@
1-
<p align="center"><a href="https://pgflow.dev" target="_blank" rel="noopener noreferrer"><img src="logo.png?raw=true" alt="pgflow logo"></a></p>
2-
3-
### Where complex becomes clockwork.
4-
5-
> "Things just happen. What the hell. And the reason things just happen is that a hundred billion other things just happened, all working unheeded and unseen, to make sure that they do."
6-
>
7-
> — **Terry Pratchett, "Last Continent"**, reflecting on the elegant machinery of complex systems
8-
9-
## Overview
10-
11-
pgflow is a workflow orchestration system that runs directly in your Postgres database - ideal for building reliable AI workflows, background jobs, and data pipelines on Supabase without external services.
12-
13-
The system combines:
14-
15-
- **[SQL Core](./pkgs/core/)** - Workflow state management natively in Postgres with ACID compliance
16-
- **[TypeScript DSL](./pkgs/dsl/)** - Type-safe workflow definitions with automatic inference
17-
- **[TypeScript Client](./pkgs/client/)** - Client library for starting workflows and monitoring real-time progress
18-
- **[Edge Worker](./pkgs/edge-worker/)** - Auto-respawning task processor that handles retries and concurrency
19-
- **[CLI Tools](./pkgs/cli/)** - One-command setup with automatic schema migrations
20-
21-
## Documentation
22-
23-
The pgflow documentation is [available on pgflow.dev](https://pgflow.dev).
24-
25-
## Getting help
26-
27-
File an issue on [GitHub](https://github.com/pgflow-dev/pgflow/issues/new) or join our [Discord](https://pgflow.dev/discord/).
1+
<p align="center"><a href="https://pgflow.dev/" target="_blank" rel="noopener noreferrer"><img src="logo-with-text.svg" alt="pgflow logo" width="450"></a></p>
2+
3+
<p align="center">
4+
<strong>AI workflows in Supabase, no extra infra.</strong>
5+
<br>
6+
TypeScript workflows with full autocomplete, zero boilerplate, automatic retries and realtime progress. Built on Postgres + Edge Functions.
7+
</p>
8+
9+
<p align="center">
10+
<a href="https://pgflow.dev">Docs</a> |
11+
<a href="https://demo.pgflow.dev">Demo</a> |
12+
<a href="https://github.com/pgflow-dev/pgflow">GitHub</a> |
13+
<a href="https://pgflow.dev/discord/">Discord</a>
14+
<br>
15+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
16+
<a href="https://supabase.com"><img src="https://img.shields.io/badge/Built%20for-Supabase-3ECF8E?logo=supabase" alt="Built for Supabase"></a>
17+
</p>
18+
19+
<p align="center">
20+
<em style="font-size: 1.2em;">"A workflow engine built on Supabase primitives."</em>
21+
<br>
22+
<strong>Paul Copplestone, CEO, Supabase</strong> (<a href="https://x.com/kiwicopple/status/1990686524229181856">via X</a>)
23+
</p>
24+
25+
<p align="center">
26+
<img src="dag-animation.svg" alt="pgflow DAG execution showing parallel steps with automatic retry" width="400">
27+
</p>
28+
29+
## Quick Start
30+
31+
```bash
32+
# Install pgflow in your Supabase project
33+
npx pgflow@latest install
34+
35+
# Restart Supabase and apply migrations
36+
npx supabase stop && npx supabase start
37+
npx supabase migrations up
38+
```
39+
40+
Then define your workflow ([full guide](https://pgflow.dev/get-started/installation/#next-steps)):
41+
42+
```typescript
43+
import { Flow } from '@pgflow/dsl';
44+
45+
new Flow<{ url: string }>({ slug: 'analyzeArticle' })
46+
.step({ slug: 'scrape' }, (input) => scrapeWebsite(input.run.url))
47+
.step({ slug: 'summarize', dependsOn: ['scrape'] }, (input) =>
48+
summarize(input.scrape)
49+
)
50+
.step({ slug: 'extractKeywords', dependsOn: ['scrape'] }, (input) =>
51+
extractKeywords(input.scrape)
52+
)
53+
.step(
54+
{ slug: 'publish', dependsOn: ['summarize', 'extractKeywords'] },
55+
(input) =>
56+
publish({ summary: input.summarize, keywords: input.extractKeywords })
57+
);
58+
```
59+
60+
This replaces ~240 lines of queue setup, state management, and coordination code. [See full comparison](https://supabase.com/blog/processing-large-jobs-with-edge-functions)
2861

2962
## Why pgflow?
3063

31-
When you need more than just isolated background jobs, but don't want the complexity of external orchestration systems:
64+
Building workflows in Supabase today means wiring together pgmq, pg_cron, state tables, and Edge Functions yourself. It works, but it's tedious.
3265

33-
- **Postgres as the Single Source of Truth** - All definitions, state, and history in your database
34-
- **Zero Infrastructure** - No external services, dashboards, or control planes
35-
- **Type-Safe Workflows** - Full compile-time safety between workflow steps
36-
- **Reliable Background Jobs** - Automatic retries with backoff and observability
66+
**pgflow gives you:**
67+
68+
- **Declarative workflows** - Define steps and dependencies in TypeScript. pgflow handles queues, state, and coordination.
69+
- **Built for Supabase** - Runs entirely in your existing project. No Redis, no Temporal, no external services.
70+
- **AI-ready** - Automatic retries with exponential backoff for flaky LLM APIs. Per-step, not per-workflow.
71+
- **Parallel processing** - Fan out over arrays with independent retries. If 3 of 100 items fail, only those 3 retry.
72+
- **Full observability** - All workflow state in Postgres. Query runs, debug failures, inspect outputs with SQL.
73+
- **Flexible triggers** - Start from your app, database triggers, pg_cron, or direct SQL calls.
3774

3875
## What can you build?
3976

40-
- **AI Workflows** - Chain LLMs, scrape data, reason across tools, and handle failures
41-
- **Background Jobs** - Process emails, files, and scheduled tasks with full visibility
42-
- **Data Pipelines** - Extract, transform, and load data with built-in dependency handling
77+
- **AI Pipelines** - Scrape websites, chunk content, generate embeddings, summarize with LLMs. Each step retries independently when APIs flake.
78+
- **Background Jobs** - Process uploads, send emails, sync data. Reliable task queue processing without Redis or external services.
79+
- **RAG Pipelines** - Chunk documents, generate embeddings, index content. Perfect for AI applications with multi-step LLM chains.
80+
- **Data Workflows** - ETL pipelines, scheduled imports, multi-step transformations. All orchestrated in Postgres.
4381

44-
## How pgflow works
82+
See how pgflow compares to [Trigger.dev](https://pgflow.dev/comparisons/trigger/), [Inngest](https://pgflow.dev/comparisons/inngest/), [DBOS](https://pgflow.dev/comparisons/dbos/), and [Vercel Workflows](https://pgflow.dev/comparisons/vercel-workflows/).
4583

46-
1. **Define workflows using TypeScript DSL**
47-
2. **Compile them to SQL migrations**
48-
3. **Deploy as Supabase Edge Functions**
49-
4. **Trigger workflows from your app or SQL**
84+
## How it works
5085

51-
The execution system handles the rest - scheduling steps when dependencies complete, retrying failed tasks, and aggregating results automatically.
86+
1. **Define workflows** using the TypeScript DSL
87+
2. **Compile** them to SQL migrations
88+
3. **Deploy** as Supabase Edge Functions
89+
4. **Trigger** from your app, SQL, or pg_cron
5290

53-
## Packages
91+
The execution engine handles scheduling, retries, and result aggregation automatically.
5492

55-
| Package | Description |
56-
| -------------------------------------- | ----------------------------------------------------------------------- |
57-
| [cli](./pkgs/cli/) | Command-line interface for installing and compiling flows |
58-
| [client](./pkgs/client/) | TypeScript client for starting workflows and monitoring real-time progress |
59-
| [core](./pkgs/core/) | SQL Core for the workflow engine - foundational tables and functions |
60-
| [dsl](./pkgs/dsl/) | TypeScript DSL for defining flows with type inference |
61-
| [edge-worker](./pkgs/edge-worker/) | Task queue worker for Supabase Edge Functions with reliability features |
62-
| [website](./pkgs/website/) | Documentation site |
63-
| [example-flows](./pkgs/example-flows/) | Example workflow definitions |
64-
65-
## Resources
93+
## Packages
6694

67-
- 📖 **Documentation**: [pgflow.dev](https://pgflow.dev)
68-
- 🚀 **Demo**: [pgflow-demo.netlify.app](https://pgflow-demo.netlify.app)
69-
- 🛠️ **Getting Started**: [pgflow.dev/getting-started](https://pgflow.dev/getting-started)
95+
| Package | Version | Description |
96+
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
97+
| [pgflow](./pkgs/cli/) | [![npm](https://img.shields.io/npm/v/pgflow)](https://www.npmjs.com/package/pgflow) | CLI for installing and compiling flows |
98+
| [@pgflow/core](./pkgs/core/) | [![npm](https://img.shields.io/npm/v/@pgflow/core)](https://www.npmjs.com/package/@pgflow/core) | SQL Core - foundational tables and functions |
99+
| [@pgflow/dsl](./pkgs/dsl/) | [![npm](https://img.shields.io/npm/v/@pgflow/dsl)](https://www.npmjs.com/package/@pgflow/dsl) | TypeScript DSL for defining flows with type inference |
100+
| [@pgflow/edge-worker](./pkgs/edge-worker/) | [![JSR](https://jsr.io/badges/@pgflow/edge-worker)](https://jsr.io/@pgflow/edge-worker) | Task queue worker for Supabase Edge Functions |
101+
| [@pgflow/client](./pkgs/client/) | [![npm](https://img.shields.io/npm/v/@pgflow/client)](https://www.npmjs.com/package/@pgflow/client) | TypeScript client for starting and monitoring workflows |
70102

71103
## Releases
72104

73-
- 📋 **Release Process**: See [RELEASES.md](./RELEASES.md) for how versions are managed and published
74-
- 📦 **Snapshot Releases**: See [SNAPSHOT_RELEASES.md](./SNAPSHOT_RELEASES.md) for testing changes before release
105+
- **Release Process**: See [RELEASES.md](./RELEASES.md) for how versions are managed and published
106+
- **Snapshot Releases**: See [SNAPSHOT_RELEASES.md](./SNAPSHOT_RELEASES.md) for testing changes before release
107+
108+
---
75109

76110
> [!NOTE]
77111
> This project and all its components are licensed under [Apache 2.0](./LICENSE) license.

0 commit comments

Comments
 (0)