Quick Start

Get the entire platform — backend API, workers, and admin UI — running on your machine with a single command.

Prerequisites

Before you start, make sure you have:

Node.js >= 20.0.0
pnpm >= 9.0.0
PostgreSQL >= 14
Redis >= 7.0 (with RedisJSON module)

Tip

Don't have pnpm? Install it globally with npm install -g pnpm@9

Setup

Clone and install

git clone <repo-url> realtime
cd realtime
pnpm install

This installs all dependencies across the monorepo (12 packages + 3 apps).

Configure environment

cp .env.example .env

Edit .env with your database and Redis credentials:

NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

REDIS_URL=redis://localhost:6379

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=realtime
POSTGRES_PASSWORD=realtime_secret
POSTGRES_DB=realtime

JWT_SECRET=your-jwt-secret-here

Start Docker services (optional)

If you don't have PostgreSQL and Redis running locally:

docker-compose up -d

Build all packages

pnpm build

Turborepo builds all 12 packages in dependency order automatically.

Start the platform

pnpm dev

This launches three services concurrently:

Service	URL	Description
Backend API	`http://localhost:3000`	Express + Socket.IO server
Workers	—	CDC reader, outbox, webhooks
Admin UI	`http://localhost:5173`	React management dashboard

Note

Database migrations run automatically on backend startup. No manual migration step needed.

First Steps After Setup

Open the Admin UI

Navigate to http://localhost:5173. On first launch you'll be prompted to create the initial admin account.

Create Your First Topic

Go to Registry → Topics in the sidebar
Click Create Topic
Enter a name like session.status, a description, and an owner
Click Save

curl -X POST http://localhost:3000/api/topics \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "session.status",
    "description": "Session status changes",
    "owner": "platform-team"
  }'

npm install @smarterservices/realtime

import { RealtimeClient } from '@smarterservices/realtime';

const realtime = new RealtimeClient({
  url: 'http://localhost:3000',
  token: 'your-jwt-token',
});

realtime.subscribe({ topic: 'session.status' });

realtime.on('event:session.status', (event) => {
  console.log('Session update:', event.payload);
});

Next Steps

Installation

Detailed installation guide with all prerequisites.

Core Concepts

Understand Topics, Schemas, Mappings and how events fan out.

Architecture

Understand the platform design and event flow.

CDC Setup

Stream database changes to real-time subscribers.

SDK Guide

Full SDK reference for browser and Node.js.