FlowFi / LiquidFlow

DeFi Payment Streaming on Stellar

Programmable, real-time payment streams and recurring subscriptions powered by Soroban smart contracts.

Overview

FlowFi (also known as LiquidFlow) is a comprehensive DeFi platform built on the Stellar network that enables continuous payment streams and recurring subscriptions using stablecoins. By leveraging Soroban smart contracts, FlowFi provides autonomous, accurate-to-the-second distribution of funds for use cases like salary payments, service subscriptions, and yield farming.

Architecture

FlowFi consists of three main components:

Frontend: Next.js application with React, TypeScript, and Tailwind CSS
Backend: Express.js API with TypeScript, Prisma ORM, and PostgreSQL
Smart Contracts: Soroban contracts written in Rust for on-chain logic

Data Flow: Contract Event → Dashboard

The diagram below shows how a stream event on-chain is intended to reach the dashboard. Each edge is labeled with its current status:

flowchart LR
    C[Soroban Contract\nstream_contract] -->|Implemented| H[Stellar Horizon]
    H -->|Planned: listener/indexer| I[Backend Indexer]
    I -->|Planned: Prisma writes| D[(PostgreSQL\nStream / StreamEvent)]
    D -->|Planned| A[Backend API]
    A -->|Planned| F[Frontend Dashboard]

Implemented: contracts/stream_contract/src/lib.rs emits real Soroban events (stream_created, stream_topped_up, etc.) on every state change.
Planned: a Horizon listener/indexer that consumes those events and writes to the Stream/StreamEvent Prisma models (schema already exists at backend/prisma/schema.prisma), a backend API that serves that data, and a frontend that consumes it live. Today, createStream returns a mock response, frontend/hooks/useContractEvents.ts is a stub, and the dashboard renders hardcoded mock data (frontend/lib/dashboard.ts).

Features

Real-time Streaming: Pay by the second for services or salaries
Recurring Subscriptions: Automate monthly or weekly payments
Soroban Powered: Secure and efficient execution on Stellar's smart contract platform
Modern Tech Stack: React 19, Next.js 16, TypeScript, Express.js, Prisma
Docker Support: Containerized deployment with Docker Compose
Developer Tools: Comprehensive API documentation with Swagger

Project Structure

FlowFi is an npm-workspaces monorepo with three top-level packages:

contracts/ — Soroban smart contracts written in Rust, managed as a separate Cargo workspace (not part of the npm workspaces below).
backend/ — Express.js + TypeScript API using Prisma ORM against PostgreSQL.
frontend/ — Next.js + Tailwind CSS dashboard, integrating with Soroban/Freighter for wallet interactions.

The root package.json declares "workspaces": ["frontend", "backend"], so a single npm install at the repo root installs dependencies for both frontend/ and backend/. contracts/ is a standalone Rust/Cargo workspace and is built independently with cargo from inside contracts/. Each package's dev/build/test scripts (npm run dev, cargo build, etc.) are still run from within that package's own directory — see Quick Start below for the exact commands.

flowfi/
├── backend/                    # Express.js + TypeScript backend
│   ├── src/
│   │   ├── app.ts             # Main application setup
│   │   ├── config/            # Configuration files
│   │   ├── controllers/       # Route controllers
│   │   ├── lib/               # Utility libraries
│   │   ├── middleware/        # Express middleware
│   │   ├── routes/            # API routes
│   │   └── validators/        # Input validation schemas
│   ├── prisma/                # Database schema and migrations
│   ├── devOps/                # Docker and deployment configs
│   └── tests/                 # Backend test suite
├── contracts/                 # Soroban smart contracts
│   ├── stream_contract/       # Core streaming logic contract
│   └── Cargo.toml             # Rust workspace configuration
├── frontend/                  # Next.js + Tailwind CSS frontend
│   ├── app/                   # Next.js app router pages
│   ├── components/            # Reusable React components
│   ├── context/               # React context providers
│   ├── hooks/                 # Custom React hooks
│   ├── lib/                   # Utility libraries
│   └── public/                # Static assets
├── .github/                   # GitHub workflows and templates
└── CONTRIBUTING.md            # Detailed contribution guidelines

Prerequisites

Before you begin, ensure you have the following installed:

Required

Node.js (v18 or higher)
npm (comes with Node.js)
Git

For Smart Contract Development

Rust (latest stable version)
Cargo (comes with Rust)

For Local Development

Docker & Docker Compose (recommended for full stack)
PostgreSQL (if not using Docker)

Optional

Stellar CLI (for contract deployment and interaction)
Prisma Studio (for database management)

Quick Start

Option 1: Docker (Recommended)

The fastest way to run the complete FlowFi stack locally:

Clone and navigate to the project:

git clone <repository-url>
cd LiquidFlow

Set up environment variables:

cp backend/.env.example backend/.env
# Edit backend/.env with your configuration

Start all services:

cd backend/devOps/docker
docker compose up --build

This starts:

PostgreSQL database on port 5432
Backend API on port 3001
Nginx reverse proxy on ports 80 and 443

In a separate terminal, start the frontend:
```
cd frontend
npm install
npm run dev
```

The frontend will be available at http://localhost:3000

Option 2: Manual Setup

Backend Setup

Install dependencies:
```
cd backend
npm install
```

Set up environment:

cp .env.example .env
# Edit .env with your database and Stellar configuration

Set up the database:

npx prisma generate
npx prisma migrate dev

Start the backend:
```
npm run dev
```

The backend API will be available at http://localhost:3001

Frontend Setup

Install dependencies:
```
cd frontend
npm install
```
Start the development server:
```
npm run dev
```

The frontend will be available at http://localhost:3000

Smart Contracts

Build the contracts:

cd contracts
cargo build --target wasm32-unknown-unknown --release

For contract development and testing:
```
cd stream_contract
cargo test
```

Development Workflow

Environment Configuration

Key environment variables in backend/.env:

# Server Configuration
PORT=3001
NODE_ENV=development

# Stellar Network
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# Database
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=liquidflow
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB}

Database Management

View database: npx prisma studio
Generate migrations: npx prisma migrate dev
Reset database: npx prisma migrate reset
Generate Prisma client: npx prisma generate

API Documentation

Once the backend is running, visit http://localhost:3001/api-docs for interactive Swagger documentation.

Testing

Backend tests: cd backend && npm test
Contract tests: cd contracts && cargo test
Frontend tests: cd frontend && npm test (if configured)

Docker Commands

Development

# Start all services
docker compose up --build

# Start in detached mode
docker compose up -d --build

# View logs
docker compose logs -f

# Stop services
docker compose down

# Stop and remove volumes (reset database)
docker compose down -v

# Rebuild specific service
docker compose up --build backend

Production

For production deployment, use the production Docker Compose configuration:

docker compose -f docker-compose.prod.yml up -d --build

Stellar Integration

Testnet Setup

Install Freighter wallet browser extension
Switch to Testnet in Freighter settings
Get testnet tokens from the Stellar testnet faucet

Contract Deployment

Build contracts for deployment:

cd contracts
cargo build --target wasm32-unknown-unknown --release

Deploy using Stellar CLI:

stellar contract deploy ./target/wasm32-unknown-unknown/release/stream_contract.wasm \
  --source <your-account> \
  --network testnet

Troubleshooting

Common Issues

Port conflicts: Ensure ports 3000, 3001, and 5432 are available
Database connection: Verify PostgreSQL is running and credentials are correct
Stellar network: Ensure you're using the correct network (testnet/mainnet)
Contract build failures: Verify Rust and wasm32 target are installed

Getting Help

Check the GitHub Issues for known problems
Review the Contributing Guide for development guidelines
Join our community discussions for support

Contributing

We welcome contributions! Please see our Contributing Guide for detailed guidelines on:

Bug reporting procedures
Pull request submission process
Code style and standards
External developer guidelines

Quick Links for Contributors

Tech Stack Details

Frontend

Framework: Next.js 16 with App Router
UI Library: React 19
Styling: Tailwind CSS 4
TypeScript: Full type safety
Stellar Integration: Soroban React, Freighter API
Icons: Lucide React
State Management: React Context

Backend

Runtime: Node.js with ES modules
Framework: Express.js 5
Language: TypeScript
Database: PostgreSQL with Prisma ORM
Validation: Zod schemas
Logging: Winston
Documentation: Swagger/OpenAPI
Testing: Vitest

Smart Contracts

Language: Rust
Platform: Soroban (Stellar)
Build Target: WASM32

DevOps

Containerization: Docker & Docker Compose
Reverse Proxy: Nginx
Version Control: Git with Husky hooks
CI/CD: GitHub Actions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Stellar Development Foundation for the Soroban platform
All contributors who help improve FlowFi
Open source community for the tools and libraries that make this project possible

Contributors

This project follows the all-contributors specification. Contributions of any kind welcome!

Name		Name	Last commit message	Last commit date
Latest commit History 196 Commits
.github		.github
.husky		.husky
backend		backend
contracts		contracts
frontend		frontend
.all-contributorsrc		.all-contributorsrc
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pr_102_diff.txt		pr_102_diff.txt

Folders and files

Latest commit

History

Repository files navigation

FlowFi / LiquidFlow

Overview

Architecture

Data Flow: Contract Event → Dashboard

Features

Project Structure

Prerequisites

Required

For Smart Contract Development

For Local Development

Optional

Quick Start

Option 1: Docker (Recommended)

Option 2: Manual Setup

Backend Setup

Frontend Setup

Smart Contracts

Development Workflow

Environment Configuration

Database Management

API Documentation

Testing

Docker Commands

Development

Production

Stellar Integration

Testnet Setup

Contract Deployment

Troubleshooting

Common Issues

Getting Help

Contributing

Quick Links for Contributors

Tech Stack Details

Frontend

Backend

Smart Contracts

DevOps

License

Acknowledgments

Contributors

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages