Fluxo

Fluxo is a high-performance, distributed automation engine inspired by Zapier. It empowers users to build sophisticated workflows that connect different services, triggered by real-time events and executed through a resilient, event-driven architecture.

---

✨ Features

• 🏗️ Visual Workflow Designer: Drag-and-drop interface powered by React Flow to build complex multi-step "Zaps".
• ⚡ Event-Driven Execution: Scalable processing using Kafka and the Transactional Outbox Pattern for guaranteed message delivery.
• 🔗 Versatile Integrations:
  • Triggers: Webhooks (HTTP Catch-hooks).
  • Actions: Email notifications, Solana blockchain transactions, and more.
• 🛠️ Developer-First: Fully type-safe monorepo built with Turborepo and pnpm.
• 📊 Robust State Management: Built on PostgreSQL with Prisma ORM for reliable data handling.

---

🏗️ Architecture

Fluxo uses a distributed system design to ensure high availability and reliability. When a trigger event occurs, it isn't just "executed"; it's safely persisted and processed through an asynchronous pipeline.

High-Level Flow

graph TD
    A[External Event / Webhook] -->|HTTP POST| B[Hooks App]
    B -->|Persist ZapRun + Outbox| C[(PostgreSQL)]
    D[Sweeper App] -->|Poll Outbox| C
    D -->|Publish Event| E[Kafka]
    E -->|Consume| F[Processor App]
    F -->|Execute Action 1| G[External Service]
    F -->|Re-queue for Stage N+1| E
    F -->|Done| H[Update Status]

Loading

Component Breakdown

• apps/frontend: The user interface for creating Zaps and monitoring runs.
• apps/backend: The management API for Zaps, triggers, and user authentication.
• apps/hooks: A specialized, lightweight service to ingest incoming webhooks at scale.
• apps/sweeper: Implements the Transactional Outbox Pattern, ensuring no events are lost between the DB and Kafka.
• apps/processor: The worker engine that consumes Kafka events and executes the logic for each stage.
• packages/db: Shared Prisma schema and client used across all services.
• packages/kafka: Centralized Kafka client configuration.

---

🚀 Getting Started

Prerequisites

• Node.js (v18+)
• pnpm
• Docker (for Kafka & Postgres)

1. Clone & Install

git clone https://github.com/samarkun23/Fluxo.git
cd Fluxo
pnpm install

2. Infrastructure Setup

Spin up Kafka and PostgreSQL (or use your own):

# Example Kafka setup via Docker
docker run -d --name kafka-fluxo -p 9092:9092 -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 bitnami/kafka:latest

Create the Kafka topic:

docker exec -it kafka-fluxo kafka-topics.sh --create --topic zap-events --bootstrap-server localhost:9092

3. Environment Configuration

Create .env files in the following locations based on their respective .env.example:

• packages/db/.env (DATABASE_URL)
• apps/backend/.env (JWT_SECRET, etc.)
• apps/hooks/.env
• apps/processor/.env
• apps/sweeper/.env

4. Database Migration

cd packages/db
pnpm dlx prisma migrate dev
pnpm dlx prisma generate

5. Run the Engine

You can start the entire stack in development mode using Turbo:

pnpm dev

---

🛠️ Tech Stack

Layer	Technology
Monorepo	Turborepo
Frontend	Next.js 15, React Flow, Tailwind CSS 4
Backend	Express, TypeScript
Database	PostgreSQL, Prisma ORM
Messaging	Apache Kafka (kafkajs)
Styling	Lucide React, Shadcn UI

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

📧 Contact

Samar - samarkun4@gmail.com

Project Link: https://github.com/samarkun23/Fluxo

---

Built with ❤️ by the Fluxo Team