Real-time Actions and Shared Records

Why the WebSocket/RPC service exists, what business areas it covers, and how access and updates work.

The real-time service is a long-running PHP process used by the admin portal and compatibility API. It performs many reads and changes and can immediately tell connected admin screens that a record changed.

It is best understood as an older application service, not merely as a socket transport.

Why it exists

Ordinary HTTP handles one request and closes. The real-time service stays alive, so it can:

keep a shared catalogue of business actions;
answer compatibility requests;
broadcast “this record changed” events to open admin screens;
run regular checks while the process is active;
expose uploads and a health check beside the socket endpoint.

sequenceDiagram
    participant Caller as Admin or compatibility API
    participant RPC as Real-time service
    participant Rule as Business provider
    participant DB as PostgreSQL
    participant Screens as Connected admin screens

    Caller->>RPC: action name, token, arguments, request ID
    RPC->>Rule: validate and run action
    Rule->>DB: read or change records
    DB-->>Rule: result
    Rule-->>Screens: record-updated event when needed
    Rule-->>RPC: success or error
    RPC-->>Caller: result with matching request ID

The request ID prevents one caller from accepting another caller's response.

Access rules

Most actions begin with a token. The service validates it and loads the active staff user or member. Staff can use the actions allowed by their role and scope. Members can call only an explicit list of member-safe actions.

The allow-list includes their own bookings and requests, profile/password work, available boats and places, balances, files, issues, check-in/service data, and selected payment operations. Being able to connect to the socket does not grant permission to call every action.

Shared create, read, update, and activation behavior

Many settings and records use one common pattern:

list active or optionally inactive records;
get one record;
return a plain array for compatibility clients;
create or update a record;
activate or deactivate it;
broadcast an update after a successful change.

This common behavior serves companies, regions, locations, boat types, boats, facilities, checklist items, extra services, Frog categories, phones, videos, notifications, newsletters, prices, app versions, and several logs/settings.

Common behavior does not mean all records have the same business rules. For example, boat availability, duplicate member email, price category, and booking overlap receive extra checks.

Complete business capability catalogue

Area	What the real-time layer contributes
Staff users	Sign-in tokens, current user, create/update/deactivate, password work, role and scope information.
Members	Account records, sign-in/password, current member, filters, ratings, balances/transactions, invoices, and newsletter selection.
Bookings	Create/update, availability, dates/status, calendar data, service requests, check-in/out fields, issues, extra services, fuel, engine hours, cash points, and payment helpers.
Booking requests	Create/update, active list, date/duplicate checks, reserve/solve/reject/cancel states.
Fleet	Boat records, available boats, measured values, fuel level, check-in/service data, issue records, PDFs, and safe deactivation checks.
Fleet structure	Companies, regions, locations, categories, boat types, facilities, checklists, and extra-service choices.
Maintenance	Frog categories, boat issues, issue history by member, and service check-ins.
Money	Price records, subscriptions, invoices, saved-card operations, fuel charges, and member balances.
Communication	Notification templates, notification records, newsletters, SMS success/failure records, password email, and reminders.
Content and files	Upload/retrieval, videos, tutorial categories and lists, phone contacts, polls, and generated boat PDFs.
Operations and reports	Dashboard data, report generation, scheduled-task calls, Salesforce logs, and app-version settings.

Important business checks

Booking overlap

When a booking is created or changed, the service checks for another active booking on the same boat and time. A staff administrator can explicitly confirm an overlap; otherwise the member or operator must choose another time.

Duplicate member email

Creating or updating a member checks whether the email is already attached to another member record. This avoids two accounts competing for the same sign-in identity.

Duplicate booking request

For new requests, the service checks whether the member already has a booking or a similar request for the relevant dates. This prevents repeated submissions from silently creating multiple items for staff.

Safe deactivation

Boats, types, places, regions, companies, and services can have dependent data. Dedicated “check before deactivation” actions let the UI warn the operator before hiding something that is still in use.

Live updates and their limit

After a supported record changes, the service broadcasts an update event. Connected screens can then reload the affected data instead of waiting for a manual refresh.

The event means “something changed”; it is not a guaranteed durable message queue. A disconnected browser can miss it and must still be able to reload the current database state later.

Inactive connections are closed after a period without activity so abandoned browser sessions do not remain forever.

Technical reference

The server starts in agapi/php/start.php; App loads the providers and action registry. WebsocketClient receives {rpc, data, uid} messages, and AbstractProvider handles common token checks, response shapes, shared record operations, and update broadcasts. The HTTP compatibility bridge is agapi/api/src/Ws.php.

On this page