# Qalqul: stateless migration, real-time systems and task dispatching

Source: https://www.alouaniyoussef.com/projects/qalqul-realtime

- Kind: employer
- Status: shipped
- Company: Qalqul Engine
- Updated: 2026-11-19

Moving Qalqul's services to stateless, horizontally scaled processes with real-time messaging, a task dispatcher, and the infrastructure behind them.

## Problem

Qalqul's services kept sessions and connections in memory, which tied each user to one process: scaling meant bigger servers, and a restart dropped live conversations. As clients grew, the contact centre also needed to dispatch work (conversations, calls, tickets) to the right agent in real time, and the infrastructure had to keep up.

## Constraints

- **No dropped conversations**: deployments and restarts must not cut agents or customers off.
- **Real time**: messages, ticket changes and agent states appear instantly across many agents.
- **Fair dispatching**: tasks go to available, skilled agents, with no task lost or assigned twice.
- **Small team**: infrastructure has to be simple to run and repeat for each client.

## Architecture

<LayerDiagram
  title="Qalqul stateless real-time platform"
  desc="Stateless API and WebSocket processes run behind a load balancer. Sessions and presence live in Redis, and a pub/sub layer fans real-time events out across processes. A task dispatcher pulls conversations, calls and tickets from queues and assigns them to available agents."
  layers={[
    { caption: 'Edge', nodes: [{ label: 'Load balancer', sub: 'Nginx' }] },
    { caption: 'Stateless services', nodes: [{ label: 'API processes' }, { label: 'WebSocket gateways', sub: 'real time', accent: true }] },
    { caption: 'Shared state', nodes: [{ label: 'Sessions & presence', sub: 'Redis' }, { label: 'Pub/sub fan-out' }, { label: 'Task queues' }] },
    { caption: 'Dispatching', nodes: [{ label: 'Task dispatcher', sub: 'skills · availability', accent: true }, { label: 'Agents' }] },
  ]}
/>

## Key decisions

1. **State out of the process.** Sessions, presence and connection routing moved to shared stores, so any process can serve any user.
2. **Fan out through pub/sub.** A WebSocket gateway publishes once, and every gateway with a subscriber delivers.
3. **One dispatcher, explicit queues.** Assignment is centralised so a task is never given to two agents.
4. **Repeatable infrastructure.** Each client deployment is the same set of services, configured, not hand-built.

## Screenshots

- Qalqul ticketing dashboard with open, overdue and unassigned counts, a performance chart, and tickets by pipeline stage, channel and priority. Tickets, counts and queues update live for every agent.
- Qalqul new-interaction dialog with a call queue selector and a phone dial pad over the ticketing dashboard. Interactions are dispatched to queues and agents in real time.

## Results

Numbers to come.

## Stack and links

Node.js, TypeScript, WebSockets, Redis, RabbitMQ, Docker Compose, Nginx
