System Architecture

Last Updated: February 18, 2026

This document outlines the technical architecture of HZ Chat and clarifies how data flows through the system.

HZ Chat is built as a session-based, real-time messaging system. Messages are transmitted through a WebSocket-based relay layer and exist only for the duration of an active session. The system does not implement message archiving, historical indexing, or long-term storage at the application level.

File attachments are stored in object storage with enforced expiration rules. Upon expiration, files are permanently deleted and are not recoverable.

The architecture is intentionally minimal. Core components include:

• Connection Manager (session lifecycle control)
• Room Manager (temporary room coordination)
• Client Handler (real-time message relay)
• Ephemeral Storage Layer (short-lived file handling)

All components are designed to prioritize real-time delivery over persistence.

System Architecture Topology

HZ Chat is built around a real-time relay architecture with no message persistence.

Messages are processed for immediate delivery and are not stored for long-term retention.

[ Client ]
│
▼ (HTTPS / WSS)
[ Cloudflare Edge Network ]
│
▼ (TLS termination + forwarding)
[ Nginx Gateway ]
│
▼
[ Go Application Node (In-Memory Processing) ]
│
├── NATS Core (Message broadcast, memory-only)
├── Redis (Online state & quota control, persistence disabled)
├── PostgreSQL (Account & room metadata)
└── Cloudflare R2 (Temporary file storage, 24h lifecycle policy)

Under normal operating conditions, chat messages exist only in the runtime memory of the Go application node and within the in-memory broadcast flow of NATS. They are not written to databases or persistent storage systems.

Component Responsibilities

This section describes the role of each system component in the data flow and clarifies whether it involves message persistence.

Cloudflare Edge Network

• Acts as the global entry point for incoming traffic
• Terminates TLS connections and forwards requests to the origin server over HTTPS
• Provides DDoS protection, basic rate limiting, and network acceleration

HZ Chat does not configure Cloudflare to store or persist chat message content.

Cloudflare may generate short-term infrastructure logs (such as security or performance logs) in accordance with its platform-level policies and agreements.

Nginx Entry Layer

• Acts as a reverse proxy, routing incoming traffic to Go service nodes
• Handles basic access control and request forwarding

The server retains standard access logs for operational diagnostics and abuse prevention.

IP addresses recorded in logs are anonymized at the application layer:

• IPv4: the last octet is zeroed (e.g., 192.168.1.23 → 192.168.1.0)
• IPv6: the latter portion is truncated and compressed

Access logs do not contain chat message content.

Go Service Nodes

• Manage WebSocket session lifecycle
• Handle room lifecycle and active participant state
• Forward messages in memory

Chat messages exist only within in-memory runtime structures for real-time broadcasting.

Structured error logs are recorded for operational stability and debugging purposes.
These logs do not include chat message content.

NATS Core

• Used for inter-node message broadcasting
• Operates in memory-only mode
• Disk storage is not enabled

NATS does not retain historical messages and is used solely for real-time distribution.

Redis

• Used for online presence tracking and rate limiting
• Persistence is disabled (RDB and AOF are not enabled)

Redis data exists only as runtime state.

PostgreSQL

• Stores account information
• Stores room metadata (e.g., room identifiers)

Chat messages are not stored in the database.

Cloudflare R2

• Used for temporary file storage (e.g., user-initiated uploads)
• Files follow a lifecycle policy for automatic deletion (currently 24 hours)

The file storage system is independent from the chat message processing pipeline.

Message Data Lifecycle

The core design principle of HZ Chat is:

Messages are used exclusively for real-time transmission and are not stored as historical records.

Message Transmission Flow

1. A user establishes a secure connection via HTTPS / WSS.
2. The message reaches a Go service node.
3. The message is immediately published to a NATS Core in-memory channel.
4. Online members in the same room receive the message in real time.

This entire process occurs in memory and does not trigger disk writes.

Zero-Persistence Architecture

• Chat content is not written to PostgreSQL.
• Chat content is not written to Redis.
• Chat content is not written to log files.
• No historical message replicas are generated.
• Server restarts do not restore any previous chat messages.

If a server restarts unexpectedly or a room instance terminates, prior messages cannot be recovered.

This behavior is enforced by system design and is not configurable at the application level.

Session Expiration Mechanism

Rooms are automatically terminated under the following conditions:

• All participants have been absent for more than 3 minutes.
• The room has been inactive for 30 minutes.

Once expiration is triggered:

• The in-memory room structure is destroyed.
• The associated NATS channel becomes inactive.
• Redis presence indexes expire.
• No recoverable data replicas remain.

Chat content becomes technically unrecoverable once the runtime state is cleared.

Data Classification and Storage Boundaries

Design Trade-off: No End-to-End Encryption

HZ Chat uses HTTPS / WSS for transport-layer encryption but does not implement end-to-end encryption (E2EE).

This is a deliberate architectural decision.

E2EE introduces additional complexity, including:

• Client-side key generation and storage
• Multi-device key synchronization
• Key recovery challenges
• Reduced server-side operational control

Because the system does not implement message persistence, message data exists only within active runtime memory during live sessions.

The system is designed as a real-time utility tool, not as a high-security adversarial communication platform.

The goal is to minimize long-term data exposure while maintaining operational simplicity and predictable behavior.

Version & Updates

This document reflects the current system architecture and data handling design of HZ Chat as of the effective date above.

If material changes are made to data categories, storage mechanisms, or retention policies, this document will be updated accordingly.

In the event of any inconsistency between this document and the Privacy Policy, the Privacy Policy shall prevail.

This document provides technical transparency and does not constitute a legal agreement.