NotiFlow App

A production-ready standalone notification service. Deploy it, call the REST API from your backend, and let users connect via WebSocket — no library integration required.

Overview

notiflow-app is a self-contained notification delivery service built on top of notiflow-spring-boot-starter. It exposes a REST API for managing users, topics, API keys, and dispatching notifications, and delivers those notifications to end-user clients over persistent WebSocket connections.

Getting Started

Prerequisites

• Java 21 JDK
• Maven (system mvn)
• PostgreSQL 16 — or use the included docker-compose.yaml
• The sibling projects must be installed locally first: mvn install in both notiflow-core and notiflow-spring-boot-starter

Build & run

# Start PostgreSQL
docker-compose up -d

# Build
mvn clean package

# Run
java -jar target/notiflow-app-1.0.0-SNAPSHOT.jar

Default endpoints

First-run setup

Liquibase seeds an admin account with setup_complete = false on first boot. You must set the admin password before any authenticated call:

# Check setup status
curl http://localhost:8080/api/auth/status

# Set admin password (min 6 characters)
curl -X POST http://localhost:8080/api/auth/setup \
    -H "Content-Type: application/json" \
    -d '{"password":"changeme"}'

Architecture

JPA-backed implementations

Admin Login (JWT + refresh tokens)

Short-lived JWTs for API access paired with long-lived rotating refresh tokens stored as HttpOnly cookies.

# Login — returns access token + sets refresh_token cookie
curl -c cookies.txt -X POST http://localhost:8080/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"username":"admin","password":"changeme"}'

# Use token on subsequent calls
curl -H "Authorization: Bearer <accessToken>" http://localhost:8080/api/users

# Rotate refresh token
curl -b cookies.txt -c cookies.txt -X POST http://localhost:8080/api/auth/refresh

# Logout
curl -b cookies.txt -X POST http://localhost:8080/api/auth/logout

API Key Authentication

Issue keys from the admin panel and pass them via the X-API-Key header. Only the SHA-256 hash is stored — the raw key is shown once at creation.

# Create a key (JWT required)
curl -X POST http://localhost:8080/api/admin/api-keys \
    -H "Authorization: Bearer <jwt>" \
    -H "Content-Type: application/json" \
    -d '{"name":"order-service"}'

# Use it on notification / user / topic / stats endpoints
curl -H "X-API-Key: nf_<key>" http://localhost:8080/api/stats

WebSocket Token Authentication

Each user gets a bearer token (prefixed nfu_) when registered via POST /api/users. Pass it in the WebSocket URL query string. Tokens can be regenerated via POST /api/users/{id}/regenerate-token.

const ws = new WebSocket('ws://host:8080/ws/notifications?token=nfu_<token>');

On connection WebSocketAuthenticator hashes the token with SHA-256, looks it up in app_users, and stores the user's externalId in the session. Inactive users are rejected with close code 1008 VIOLATED_POLICY.

REST API — Auth /api/auth

REST API — Users /api/users

Requires ROLE_ADMIN (JWT) or ROLE_API_CLIENT (API Key).

REST API — Topics /api/topics

Requires ROLE_ADMIN or ROLE_API_CLIENT. Topics are created implicitly on subscribe.

REST API — Notifications /api/notifications

Requires ROLE_ADMIN or ROLE_API_CLIENT. All three endpoints share the same request body.

Request body (NotificationRequest)

curl -X POST http://localhost:8080/api/notifications/user/user-42 \
    -H "X-API-Key: nf_<key>" \
    -H "Content-Type: application/json" \
    -d '{"type":"order","title":"Order shipped","message":"Your order is on its way","priority":"HIGH"}'

REST API — API Keys /api/admin/api-keys

Requires ROLE_ADMIN (JWT only).

REST API — Stats /api/stats

Requires ROLE_ADMIN or ROLE_API_CLIENT.

Notification Flow (End-to-End)

Direct user notification

1. Caller sends POST /api/notifications/user/{userId}
2. NotificationController converts the request to a Notification and calls NotificationService.sendToUser(userId, notification)
3. User online: DefaultNotificationService finds the session in InMemorySessionRegistry, serializes the notification into an Envelope of type NOTIFICATION, and sends it via Session.getBasicRemote().sendText(...)
4. User offline: JpaNotificationQueue.enqueue(userId, notification) inserts a row into queued_notifications
5. If ackEnabled = true, AuditingDeliveryTracker.track(...) writes a notification_audit row with sentAt = now()
6. On reconnect, queued notifications are flushed as QUEUED-type envelopes
7. Client sends back ACK → AuditingDeliveryTracker.acknowledge(...) stamps ackedAt

Topic notification

1. Caller sends POST /api/notifications/topic/{topic}
2. JpaTopicService.getSubscribers(topic) returns the set of externalId values
3. sendToUser is called for each subscriber — online delivers live, offline queues

Broadcast

1. Caller sends POST /api/notifications/broadcast
2. SessionRegistry.getAll() is iterated and each live session receives the notification
3. Offline users do not receive broadcast notifications — no queue entry is created

WebSocket Client Guide

Connecting

const ws = new WebSocket('ws://host:8080/ws/notifications?token=nfu_<token>');

ws.onmessage = (event) => {
    const { type, id, payload } = JSON.parse(event.data);

    if (type === 'NOTIFICATION' || type === 'QUEUED') {
        console.log(payload.title, payload.message, payload.priority);
        // ACK to stop retries
        ws.send(JSON.stringify({ type: 'ACK', payload: { notificationId: id } }));
    } else if (type === 'PING') {
        ws.send(JSON.stringify({ type: 'PONG' }));
    }
};

// Reconnect with exponential back-off on close / error
ws.onclose = () => setTimeout(connect, backoff());

Message types

Built-in Admin Panel

NotiFlow App ships a lightweight admin panel as a static resource served directly by the application — no separate deployment needed. Open it in a browser once the app is running:

http://localhost:8080/admin.html

The panel is a single vanilla-JS page that communicates with the REST API using the admin JWT cookie from POST /api/auth/login. It provides:

• Live stats — connected user count and queued message total, auto-refreshed every 5 seconds
• Send notifications — broadcast to all, send to a specific user ID, or send to a topic; choose type, title, message, and priority
• Topic management — subscribe a user to a topic, unsubscribe, and browse the current topic list with subscriber counts
• Response log — every API action is logged with its HTTP status and response body for quick debugging

Vue Admin Dashboard

notiflow-admin-dashboard is a standalone Vue 3 + Vite SPA with a full admin interface. It connects to the notiflow-app REST API and provides a richer management experience than the built-in panel.

Features

Development

# Install dependencies
cd notiflow-admin-dashboard
npm install

# Start dev server (proxies API calls to notiflow-app on :8080)
npm run dev

# Build for production
npm run build
# Output: dist/ — serve with any static host or nginx

Database Schema

All tables are created and versioned by Liquibase (classpath:db/changelog/db.changelog-master.yaml).

Configuration Reference

server:
  port: 8080

spring:
  datasource:
    url: ${DB_URL:jdbc:postgresql://localhost:5432/notiflow}
    username: ${DB_USERNAME:notiflow}
    password: ${DB_PASSWORD:notiflow}

notiflow:
  web-socket:
    path: '/ws/notifications'
  queue:
    ttl: 10m # offline notification retention
    max-per-user: 50 # oldest dropped when exceeded
  delivery:
    ack-enabled: true
  heartbeat:
    enabled: true
    ping-interval: 30s

app:
  jwt:
    secret: ${JWT_SECRET:change-me-in-production-at-least-32-bytes!!}
    access-token-expiration: 3600 # seconds
    refresh-token-expiration: 2592000 # 30 days
  cors:
    allowed-origins: ${CORS_ORIGINS:http://localhost:5173}

Environment variables

Docker Deployment

Included docker-compose.yaml

The repository includes a compose file that starts both PostgreSQL and the application:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: notiflow
      POSTGRES_USER: notiflow_user
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - notiflow-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U notiflow_user -d notiflow"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

  app:
    image: dpustula/notiflow-app:latest
    ports:
      - "8080:8080"
    environment:
      DB_URL: jdbc:postgresql://postgres:5432/notiflow
      DB_USERNAME: notiflow_user
      DB_PASSWORD: changeme
      JWT_SECRET: your-secret-key-here
      CORS_ORIGINS: http://localhost:3080
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - notiflow-net
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    # Uncomment to set resource limits:
    # deploy:
    #   resources:
    #     limits:
    #       cpus: '1'
    #       memory: 512M

  dashboard:
    image: dpustula/notiflow-admin-dashboard:latest
    ports:
      - "3080:80"
    depends_on:
      - app
    networks:
      - notiflow-net
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

networks:
  notiflow-net:
    driver: bridge

volumes:
  postgres-data: