# Realtime Framework: apps without a backend API

A shared realtime database instead of a queue broker and an API server. The interface writes a task, an independent process claims it, and the result returns to the screen on its own.

## At a glance

- Type: Kol.ski's own framework
- For whom: Teams building panels, forms and automation with processes on their own machines
- Scope: Architecture model, data contracts, worker patterns
- Status: In production use, version 1.0 of the contract in preparation

## Challenge

An operations panel, a form or an audit tool needs three things at once: an interface showing live state, processes doing the work on different machines, and a way for the two to talk. The classic answer is an API server, a queue with a broker and a websocket channel: three systems to maintain before the first feature exists.

> Who is running this now, and is it still alive?

In the classic setup, answering that question takes separate monitoring. Here it was meant to follow from the architecture itself.

## Solution

The whole system rests on one Firebase Realtime Database with three branches. Every participant, a person in a browser and a process on a server, is an actor: it watches data, claims work and writes the result.

### Tasks

The interface or an automation writes a task to the `queue` branch. A worker claims it with a single write: the first successful one wins, the others see that the task is taken.

### State

The `data` branch holds the current state that the interface and the processes look at together. The result appears on screen without polling.

### Actors

In the `actors` branch every process and every open tab reports its identity, version, capabilities and heartbeat. You can see who is running and on which code.

### Permissions

Each worker has its own credentials and only the permissions its job requires. There is no single key to everything.

## Result

| Number | Meaning |
| --- | --- |
| 3 | database branches for the whole system: tasks, state, actors |
| 3 | hosts in the first trial: a server, a laptop and a Raspberry Pi |
| 0 | queue brokers and custom API servers |
| 30 | seconds is the longest gap between a process's heartbeats |

### What works

- The first trial on three hosts: each saw the others and completed the tasks addressed to it.
- Operations panels where a click in the interface starts work on a remote machine and the progress is visible live.
- Public forms that encrypt data in the browser: the database receives ciphertext and the worker decrypts it only at execution. The contact form of this website works this way.
- Long analytical jobs that publish partial progress: stage, current item and counter.
- A shared worker core: task claiming, heartbeat, version reporting and a command line in one library.

### Ahead of us

- One task lifecycle across all workers, with retries and recovery of work after a process failure.
- An event archive next to the realtime database, which holds current state, not full history.
- A comparative test against off-the-shelf queue and workflow platforms.

Realtime Framework does not replace durable execution engines such as Temporal. Where a long process has to be replayed step by step after a failure, they are the right choice.

## What it consists of

The parts of the system do not talk to each other directly. The only point of contact is the database and its data contract.

| Part | What it does | Technology |
| --- | --- | --- |
| Interface | A static site with sign-in that reads state and writes tasks straight to the database | Firebase Hosting, Firebase Auth, JavaScript |
| Realtime database | Three branches and access rules: the only place tasks and results pass through | Firebase Realtime Database, security rules |
| Workers | Separate processes on servers, virtual machines and edge devices, each with its own role and credentials | Go, Python, PM2, systemd |
| Core | A shared worker library: queue, heartbeat, version, configuration and command line | Go, JSON |

## Lessons

- The version in the heartbeat must come from the build. Typed by hand, it went stale silently and several processes reported a number they did not have.
- Claiming a task is a write, not a removal from the queue. One status field instead of moving records makes watching and debugging simpler.
- The interface is an actor, not a client. When a browser tab has an identity and a heartbeat, people and processes show up in one registry.
- A realtime database is state, not an archive. History and audit need a separate layer, planned from the start.

## Building a panel or automation?

We design applications with a live view and processes on your own machines, without a heavy backend. Tell us what you want to build.

[Discuss your project](mailto:hi@kol.ski) · [Book 30 minutes](https://calendar.app.google/CJxZPq3FqabCDMS59) · [Projects](https://kol.ski/en/projects)