PointFlow

The open-source loyalty platform you can self-host in 5 minutes.

---

PointFlow is a free, open-source, self-hostable loyalty platform for small and medium businesses. Any business — a dental clinic, coffee shop, barbershop, or retail store — can run their own loyalty programme without paying for an external SaaS.

Real problem, real niche. Existing SaaS solutions (Smile.io, LoyaltyLion) cost hundreds of dollars per month. No good open-source alternatives exist. PointFlow fills that gap.

✨ Features

• 🏆 Points & Tiers — configurable points-per-visit rules with automatic tier progression
• 🔔 Real-time Notifications — email alerts on points earned and tier changes
• 📊 Analytics Dashboard — visit history, point balances, and tier distribution
• 👤 Customer Portal — self-service portal for customers to track their rewards
• 🔐 Session Auth — stateful Redis sessions (7-day TTL) with per-session CSRF token (X-CSRF-Token header), per-tenant user isolation, and role-based staff access; session revocation is immediate
• 🛡️ Security Hardened — OWASP Top 10 audit complete: Helmet, rate limiting, account lockout, structured audit logging, cryptographic card code generation
• 🐘 Event-Driven Core — built on Apache Kafka 4.2 KRaft (no Zookeeper!)
• 🚀 Self-hosted — single docker compose up to run the entire stack

🏗️ Architecture

Browser (Next.js 16)
        │ HTTPS + session cookie
        ▼
  API Gateway (NestJS 11, port 3001)
  ├── Auth Service    (TCP, port 3003)  ──► Stateful Redis sessions, CSRF, audit log
  ├── Loyalty Engine  (TCP, port 3002)  ──► Kafka 4.2 KRaft
  └── Analytics       (HTTP + Kafka, port 3004)
                                              │
                                    Notifications Service
                                      (Kafka consumer)

  All services ↔ CockroachDB v25.2 LTS via Drizzle ORM 0.45
  (Database per Service: pf_auth, pf_loyalty, pf_notifications)

🛠️ Tech Stack

Layer	Technology	Version
Monorepo	Turborepo	2.8.12
Runtime	Node.js	24.x LTS
Language	TypeScript	5.9.x
Backend	NestJS	11.1.x
Frontend	Next.js + React	16.1.x + 19.2.x
Database	CockroachDB	v25.2.13 LTS
ORM	Drizzle ORM	0.45.x
Message Broker	Apache Kafka KRaft	4.2.0
Styling	Tailwind CSS	4.x
Package Manager	pnpm	10.x

Kafka 4.x = no Zookeeper. Kafka 4.0 (March 2025) removed Zookeeper entirely. PointFlow uses KRaft mode — one container, zero extra coordination overhead.

📁 Project Structure

pointflow/
├── apps/
│   ├── web/              # Admin dashboard (Next.js 16, port 3000)
│   └── portal/           # Customer self-service portal (Next.js 16, port 3005)
├── services/
│   ├── api-gateway/      # Public HTTP entry point (NestJS 11, port 3001)
│   ├── loyalty-engine/   # Points & tiers logic (NestJS TCP, port 3002)
│   ├── auth/             # Stateful session auth (NestJS, port 3003)
│   ├── notifications/    # Email delivery (NestJS Kafka consumer)
│   └── analytics/        # Statistics & reporting (NestJS HTTP + Kafka)
├── packages/
│   ├── typescript-config/ # Shared tsconfig (base / nextjs / nestjs)
│   ├── eslint-config/     # Shared ESLint rules
│   ├── contracts/         # TypeScript interfaces, DTOs & Kafka events
│   ├── drizzle-schemas/   # Database schemas
│   ├── types/             # Pure domain models (Settings, Entities)
│   └── utils/             # Shared helper functions (code generation, etc.)
├── infrastructure/
│   ├── docker-compose.yml        # Dev stack
│   └── docker-compose.prod.yml   # Production stack
└── scripts/
    ├── db-migrate-all.ts         # Global database migration runner
    └── db-seed-all.ts            # Global database seeding runner

🚀 Quick Start

Prerequisites

• Node.js 24+ and pnpm 10+
• Docker & Docker Compose v2

1. Clone & install

git clone https://github.com/binkowskidawid/pointflow.git
cd pointflow
pnpm install

2. Start infrastructure

docker compose -f infrastructure/docker-compose.yml up -d

This starts: CockroachDB (pf_loyalty and pf_notifications databases), Kafka 4.2 KRaft, MailHog (local email), Kafka UI, and Seq (structured log viewer).

Because PointFlow uses isolated microservices, each app and service relies on its own scoped environment configurations to ensure decoupling.

Run the following commands to create your .env files from their respective templates:

# Root (Used by Turborepo / Prisma / Global scripts)
cp .env.example .env

# Web Frontend
cp apps/web/.env.example apps/web/.env

# API Gateway
cp services/api-gateway/.env.example services/api-gateway/.env

# Loyalty Engine
cp services/loyalty-engine/.env.example services/loyalty-engine/.env

# Notifications Service
cp services/notifications/.env.example services/notifications/.env

# Auth Service
cp services/auth/.env.example services/auth/.env

Note: The default .env.example values are perfectly matched for the standard local docker compose footprint. You only need to edit them if you are changing infrastructure ports.

4. Database Setup (Migrations & Seeding)

PointFlow uses a "Database per Service" architecture. We use global scripts to manage all databases at once.

# Apply migrations to all service databases
pnpm run db:migrate

# (Optional) Seed all databases with demo data
pnpm run db:seed

5. Start development

pnpm run dev

Service	URL
Admin Dashboard	http://localhost:3000
API Gateway	http://localhost:3001
Loyalty Engine	http://localhost:3002
Auth Service	http://localhost:3003
Customer Portal	http://localhost:3005
Kafka UI	http://localhost:8090
CockroachDB UI	http://localhost:8080
MailHog	http://localhost:8025
Seq (logs)	http://localhost:5340

🗺️ Roadmap

• Stage 1 — Monorepo foundation (Turborepo, shared packages, tsconfig)
• Stage 1 — @pointflow/contracts shared package (inter-service DTOs, Kafka event types)
• Stage 1 — Code quality toolchain (Prettier, Husky, lint-staged, GitHub Actions CI)
• Stage 1 — Loyalty Engine (NestJS 11, Drizzle ORM, CockroachDB)
• Stage 1 — Admin Dashboard (Next.js 16 + React Query + Tailwind 4)
• Stage 2 — Kafka 4.2 KRaft integration
• Stage 2 — API Gateway + TCP Internal Communication
• Stage 2 — Notifications Service (Kafka Consumer)
• Stage 2 — Auth Service (Registration Flow & Validation)
• Stage 2 — Auth Service (Login & Stateful Sessions + CSRF + Frontend Auth Flow)
• Stage 2 — Auth Service (RBAC + tenant-aware dashboard flows)
• Stage 2 — Security hardening (OWASP Top 10 audit, Phases 1–4 complete)
• Stage 2 — Stateless JWT → Stateful Redis session auth + CSRF double-submit protection
• Stage 2 — Structured log aggregation (Seq + pino-seq across all services)
• Stage 3 — Customer Portal (self-service, no login required)
• Stage 3 — Analytics Service
• Stage 3 — v1.0.0 release with quickstart.sh
• Stage 4 — WebSockets real-time dashboard
• Stage 4 — JavaScript/TypeScript SDK
• Stage 4 — Swagger API docs

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

Good first issues to look for:

• Adding new notification channels (SMS via Twilio)
• Building a JavaScript SDK
• Improving test coverage
• Writing documentation

📄 License

MIT © Dawid Bińkowski

See LICENSE for details.