SOFTWARE

AlertCast

An SSE-based real-time notification push platform. The server is self-hosted, and client agents are planned to be provided as an integrated package in a subsequent phase.

v1.3.0SSE + REST + NATS JetStream

Architecture

ArchitectureThe L7 proxy routes new/reconnecting SSE requests based on the presence of a Last-Event-ID. The SSE layer has a stateless design capable of horizontal scaling (currently operating as a single instance; cluster partitioning is planned for a subsequent phase), while the REST layer handles authentication and publishing. The two layers communicate exclusively via NATS subjects (direct HTTP calls are prohibited).

Intended Use

A one-way, real-time notification channel that carries messages from your business systems to your users. It mainly delivers immediate alerts — system announcements, outages, and business events — but the same channel also handles messages that arrive on their own schedule, such as the results of async tasks.

Scalability

The primary constraint of real-time push is the long-term occupation of a TCP connection per client. As the number of users increases, this directly hits the concurrent connection limits of a single server. AlertCast designs the SSE layer as stateless and shares the same channel across all instances using NATS JetStream subject fan-out — cluster partitioning (multiple SSE instances) is planned for introduction in a subsequent phase.

Server — Components (5)

SSE Layer Handles new SSE connections, message fan-out (long-term connection pool). Stateless, horizontally scalable architecture
REST Layer Business logic + Authentication/Publishing + Reconnection Recovery (Last-Event-ID). async ORM, schema validation
Message Broker NATS JetStream — Direct REST↔SSE calls prohibited, NATS subjects only
Session Storage PostgreSQL. JWT token blacklists are managed in JetStream KV
L7 Routing L7 Proxy. SSL termination + /events new/reconnect routing

New SSE connections go to the SSE layer, reconnection recovery (Last-Event-ID) goes to the REST layer — routed by the L7 proxy.

Server — Message Channels (4 Topics)

alert.user.* Individual user notification
alert.dept.* Department-level notification
alert.broadcast System-wide broadcast
alert.admin.commands Admin commands (e.g., forced logout)

Server — Load Verification

Target Concurrent Connections: 1,000,000
Target Users: 2,000,000
Stability Verification: Verifies stability and integrity through load testing of large-scale concurrent connections and notification message fan-out

The goal is 1M connections and 2M users. Verification is ongoing, and resulting figures will be displayed alongside the measurement environment once finalized.

SUB-COMPONENT (Planned)

Client — AlertAgent

A client agent for each OS pairs with the server to receive SSE events, cache them locally, and reconnect automatically, absorbing any missed notifications. This agent is planned for a later phase. For now, the SSE events the server publishes (the 4 types below) are finalized; the client-side implementation, reconnection policy, and platform-specific behavior will be updated once the plan is confirmed.

Server-Issued Events (4 Types)

alert General notification to display to users (Title, Body, Priority)
file_ready File ready on the server — client proceeds with download
config_update Dynamically reflects server-side configuration changes to the client
force_logout Forced logout triggered by an administrator command

Missed Message Recovery Flow

Working with the server's Last-Event-ID-based replay recovery, the agent automatically reconnects and recovers missed messages from a local cache when the client loses its network connection.

Platform-Specific Behavior

The agent is designed to show native notifications and manage credentials securely on each major operating system, including Windows and macOS.

Specifications

Server (AlertCast)

Version: v1.3.0
License: Private (Internal project)
SSE Layer: Long-term connection handling, message fan-out, NATS subscription, stateless
REST Layer: Auth, publishing, reconnection recovery, async ORM, schema validation
Broker: NATS JetStream
Session Storage: PostgreSQL
Proxy: L7 Proxy (SSL termination + L7 routing)

Measurement Environment / Pending Metrics

Scalability Verification: Continuously optimizing distributed processing and message fan-out to handle the target concurrent user load

Security & Compliance

License: Private (Internal project)
Operating Environment: Self-hosted — Operates on both closed and internet networks. No external SaaS/Cloud dependencies
Authentication: JWT(HS256) Bearer + JetStream KV token blacklist (instant revocation) · shared with core-auth
Transmission: L7 Proxy TLS 1.2/1.3 termination
Layer Isolation: Direct SSE ↔ REST calls prohibited — NATS subjects or NATS req/reply only
Client Credentials: Secure credential management via integration with OS-native security storage
SBOM / Signatures: syft SBOM, cosign signatures, grype scanning (Taskfile release:*)
Tech Support: On deployment, a dedicated technical team is assigned and a patch support channel is provided

Getting Started

Requirement Review — Concurrent connection scale, notification types, client OS, security policies
Installation / Integration — Closed network deployment packages (alert-server + alert-sse images) + Client agent distribution
Operations / Monitoring — Prometheus, Grafana, Loki, Tempo, NATS subject tracking

Considering Cubiware for your organization?

We will guide you through setup and rollout tailored to your requirements and operating environment. Reach out for a demo or a proposal.