System Architecture

Fluxer is designed as a modular platform that can run as a single monolith or scale to a distributed microservices architecture. This guide explains the system components and how they interact.

Deployment Modes

Fluxer supports two deployment architectures:

Monolith (Recommended)
Microservices

All services run in a single process (fluxer_server). This is the default and recommended approach for most deployments.Advantages:

Simple deployment and operations
Lower resource overhead
No network latency between components
Easier debugging and tracing

Best for:

Small to medium communities (< 10,000 users)
Single-region deployments
Development and testing

Docker Image:

ghcr.io/fluxerapp/fluxer-server:stable

Services run as independent processes that communicate via HTTP and NATS.Advantages:

Independent scaling of components
Geographic distribution
Fault isolation
Language diversity (Node.js + Erlang)

Best for:

Large-scale deployments (> 10,000 concurrent users)
Multi-region setups
High-availability requirements

Required Configuration:

{
  "instance": {
    "deployment_mode": "microservices"
  }
}

Core Components

HTTP Services (Node.js + Hono)

All HTTP-based services are built with TypeScript, Node.js, and the Hono web framework.

API Server

Package: fluxer_api
Purpose: REST API for all application logicHandles:

User authentication and registration
Guild (community) and channel management
Message creation and history
File uploads and CDN operations
Search indexing
Admin operations

Endpoints:

/api/v1/* - Public REST API
/_health - Health check endpoint

Port: 8080 (default in monolith)

Media Proxy

Package: fluxer_media_proxy
Purpose: Image and video processing, CDN proxyingFeatures:

Dynamic image resizing and optimization
Video thumbnail generation (ffmpeg)
Signed URL verification
Optional NSFW detection (ONNX model)
External URL proxying with caching

Port: 8080/media (monolith) or dedicated port

Admin Panel

Package: fluxer_admin
Purpose: Web-based administration interfaceFeatures:

User management and moderation
Guild administration
System configuration
LiveKit voice region management
Analytics dashboard

Endpoint: /admin (monolith) or dedicated service
Authentication: OAuth2 with session tokens

Marketing Site

Package: fluxer_marketing
Purpose: Optional public landing pageFeatures:

Instance homepage
Public guild directory
Terms of service and privacy policy

Endpoint: /marketing or root path
Can be disabled in configuration.

S3 Service

Package: @fluxer/s3
Purpose: S3-compatible object storageBuilt-in filesystem-backed S3 implementation for self-hosted deployments. Supports:

Multipart uploads
Presigned URLs
Bucket management
Compatible with AWS SDK clients

Endpoint: /s3 (monolith)
Can be replaced with external S3 (AWS, MinIO, Garage, etc.).

Queue Service

Package: @fluxer/queue
Purpose: Background job processingHandles:

Email delivery
Search indexing
Image processing jobs
Data exports
Scheduled tasks

Uses NATS JetStream in microservices mode, or in-process queue in monolith.

WebSocket Gateway (Erlang/OTP)

Package: fluxer_gateway
Language: Erlang/OTP
Purpose: Real-time WebSocket connections and message routing

Why Erlang?

Erlang excels at managing millions of concurrent connections with minimal resource overhead. The BEAM VM provides:

Lightweight processes - Each WebSocket connection runs in an isolated Erlang process
Hot code reloading - Update gateway code without disconnecting users
Fault tolerance - Supervisor trees automatically restart failed connections
Built-in distribution - Native clustering across multiple nodes

Gateway Responsibilities:

Connection management - Handles WebSocket lifecycle (identify, resume, heartbeat)
Message routing - Delivers events to connected clients
Presence tracking - Maintains online/offline status and activity
Push notifications - Sends Web Push to offline users
Rate limiting - Per-connection and per-user limits

Configuration:

"services": {
  "gateway": {
    "port": 8082,
    "presence_shards": 4,
    "guild_shards": 4,
    "push_enabled": true
  }
}

Sharding allows distributing load across multiple Erlang processes. Increase shard counts for high-concurrency deployments.

Frontend Application (React + Electron)

Package: fluxer_app
Technologies: React, TypeScript, Rust (WASM), Vite The web and desktop clients are built from the same React codebase:

Web App - Served at / by fluxer_server
Desktop App - Electron wrapper with native OS integration

Rust WebAssembly Modules:

Voice codec processing (Opus)
Encryption primitives
Performance-critical operations

The compiled app is included in the fluxer_server Docker image at /usr/src/app/assets.

Data Layer

Database Options

SQLite (Default)
Cassandra (Distributed)

Best for: Single-node deployments, < 10,000 usersFluxer uses SQLite in WAL mode with optimizations:

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA cache_size = -64000;  -- 64MB cache
PRAGMA busy_timeout = 5000;

File Location: Configured in database.sqlite_path
Backups: Simple file copy (use PRAGMA wal_checkpoint(TRUNCATE) first)Limitations:

Single-writer (multiple readers OK)
No geographic replication
Limited to single server’s disk I/O

Best for: Multi-region deployments, > 10,000 users, HA requirementsApache Cassandra provides:

Multi-datacenter replication
Linear scalability
No single point of failure
Tunable consistency

Setup:

Deploy Cassandra cluster (3+ nodes recommended)

Create keyspace:

CREATE KEYSPACE fluxer
WITH replication = {
  'class': 'NetworkTopologyStrategy',
  'dc1': 3
};

Configure Fluxer:

{
  "database": {
    "backend": "cassandra",
    "cassandra": {
      "hosts": ["cassandra-1", "cassandra-2", "cassandra-3"],
      "keyspace": "fluxer",
      "local_dc": "dc1",
      "username": "cassandra",
      "password": "your-password"
    }
  }
}

See Scaling Guide for Cassandra deployment.

Caching & Coordination (Valkey/Redis)

Image: valkey/valkey:8.0.6-alpine
Purpose: High-speed cache and distributed coordination Use cases:

Session storage
Rate limiting counters
Cached API responses
Distributed locks
Ephemeral data (typing indicators, presence)

Deployment:

services:
  valkey:
    image: valkey/valkey:8.0.6-alpine
    command: [
      'valkey-server',
      '--appendonly', 'yes',
      '--save', '60', '1'
    ]
    volumes:
      - valkey_data:/data

For high availability, deploy Redis Cluster or use managed Redis (AWS ElastiCache, etc.).

Search Engines

Fluxer supports two search backends:

Meilisearch (Recommended)
Elasticsearch

Image: getmeili/meilisearch:v1.14
Best for: Most deploymentsAdvantages:

Fast setup (< 1 minute)
Low resource usage
Excellent relevance ranking
Typo tolerance out of the box

meilisearch:
  image: getmeili/meilisearch:v1.14
  environment:
    MEILI_MASTER_KEY: ${MEILI_MASTER_KEY}
  volumes:
    - meilisearch_data:/meili_data

Image: elasticsearch:8.19.11
Best for: Advanced search features, existing ES infrastructure

elasticsearch:
  image: elasticsearch:8.19.11
  environment:
    discovery.type: single-node
    xpack.security.enabled: 'false'
    ES_JAVA_OPTS: '-Xms512m -Xmx512m'
  volumes:
    - elasticsearch_data:/usr/share/elasticsearch/data

Indexed content:

Messages (with filters for channels, authors, dates)
Guilds (for discovery)
Users (for mentions and DMs)

Voice & Video Infrastructure

LiveKit SFU

Image: livekit/livekit-server:v1.9.11
Purpose: Selective Forwarding Unit for WebRTC media LiveKit handles:

WebRTC signaling (via WebSocket)
Media routing between participants
TURN/STUN for NAT traversal
Recording and egress
Simulcast and adaptive bitrate

Architecture: Fluxer API generates JWT tokens for LiveKit access. Clients connect directly to LiveKit for media. Port Requirements:

Port	Protocol	Purpose
7880	TCP	HTTP/WebSocket API (internal)
7881	TCP	RTC over TCP (fallback)
3478	UDP	TURN/STUN
50000-50100	UDP	RTP/RTCP media streams

UDP ports must be directly accessible from the internet. They cannot be proxied through Cloudflare Tunnels or similar HTTP-only services.

See Voice Setup Guide for detailed LiveKit configuration.

Message Queue (Microservices Mode)

NATS

Image: nats:2-alpine
Purpose: Inter-service communication and job queuing NATS provides:

Core NATS - Request/reply RPC between services
JetStream - Persistent message queues for background jobs

Only required in microservices mode. The monolith uses in-process communication.

nats_core:
  image: nats:2-alpine
  command: ['-c', '/etc/nats/nats.conf']
  ports:
    - '4222:4222'

nats_jetstream:
  image: nats:2-alpine
  command: ['-c', '/etc/nats/jetstream.conf', '--jetstream']
  ports:
    - '4223:4222'

Request Flow

Here’s how a typical message send request flows through Fluxer:

Resource Requirements

Monolith Deployment

Component	CPU	Memory	Storage
fluxer_server	2-4 cores	4-8 GB	-
Valkey	1 core	2 GB	1 GB
Meilisearch	1 core	1 GB	5-50 GB
SQLite	-	-	10-500 GB
Total	4-6 cores	8-12 GB	20-600 GB

Microservices Deployment (per service)

Service	CPU	Memory	Notes
API Server	2-4 cores	4 GB	Scale horizontally
Gateway	4-8 cores	8 GB	Connection-heavy
Media Proxy	2 cores	4 GB	CPU for image/video
Admin Panel	1 core	1 GB	Low traffic
Cassandra (per node)	4-8 cores	32-64 GB	See Scaling
NATS	2 cores	2 GB	JetStream needs disk

Security Considerations

Network Isolation

Use Docker networks to isolate services:

Public: Only reverse proxy and LiveKit
Internal: All other services

networks:
  public:
  internal:
    internal: true

Secret Management

Never commit secrets to version control. Use:

Environment variables for containers
Docker secrets or Kubernetes secrets
External secret managers (Vault, AWS Secrets Manager)

TLS Termination

Always terminate TLS at the reverse proxy:

Use Let’s Encrypt for free certificates
Set "public_scheme": "https" in config
Set "cookie.secure": true

Firewall Rules

Restrict access:

# Allow only necessary ports
ufw allow 80/tcp    # HTTP (redirect to HTTPS)
ufw allow 443/tcp   # HTTPS
ufw allow 3478/udp  # TURN
ufw allow 7881/tcp  # RTC TCP fallback
ufw allow 50000:50100/udp  # RTC media

Monitoring & Observability

Health Checks

All services expose health check endpoints:

# Fluxer server
curl http://localhost:8080/_health

# Valkey
valkey-cli ping

# Meilisearch
curl http://localhost:7700/health

# LiveKit
curl http://localhost:7880/

Logs

Fluxer uses structured JSON logging in production:

{
  "level": "info",
  "timestamp": "2026-03-04T12:00:00.000Z",
  "service": "api",
  "message": "Request completed",
  "request_id": "req_123",
  "method": "POST",
  "path": "/api/v1/messages",
  "status": 201,
  "duration_ms": 45
}

Centralize logs with:

Loki + Grafana
ELK Stack
Cloud logging (AWS CloudWatch, GCP Cloud Logging)

Metrics (OpenTelemetry)

Enable telemetry in config:

{
  "telemetry": {
    "enabled": true,
    "otlp_endpoint": "http://otel-collector:4318",
    "service_name": "fluxer",
    "trace_sampling_ratio": 0.1
  }
}

Exported metrics:

HTTP request rates and latencies
Database query performance
Cache hit/miss ratios
WebSocket connection counts
Message delivery times

Next Steps

Configuration

Explore all configuration options in detail

Voice Setup

Set up LiveKit for voice and video

Scaling

Scale to distributed deployments

Upgrading

Learn about upgrade procedures

Get Started

Core Features

Self-Hosting

Bot Development

WebSocket Gateway

Topics

Resources

System Architecture

Deployment Modes

Core Components

HTTP Services (Node.js + Hono)

WebSocket Gateway (Erlang/OTP)

Why Erlang?

Frontend Application (React + Electron)

Data Layer

Database Options

Caching & Coordination (Valkey/Redis)

Search Engines

Voice & Video Infrastructure

LiveKit SFU

Message Queue (Microservices Mode)

NATS

Request Flow

Resource Requirements

Monolith Deployment

Microservices Deployment (per service)

Security Considerations

Monitoring & Observability

Health Checks

Logs

Metrics (OpenTelemetry)

Next Steps

Configuration

Voice Setup

Scaling

Upgrading

Build docs developers (and LLMs) love

Get Started

Core Features

Self-Hosting

Bot Development

WebSocket Gateway

Topics

Resources

​Deployment Modes

​Core Components

​HTTP Services (Node.js + Hono)

​WebSocket Gateway (Erlang/OTP)

Why Erlang?

​Frontend Application (React + Electron)

​Data Layer

​Database Options

​Caching & Coordination (Valkey/Redis)

​Search Engines

​Voice & Video Infrastructure

​LiveKit SFU

​Message Queue (Microservices Mode)

​NATS

​Request Flow

​Resource Requirements

​Monolith Deployment

​Microservices Deployment (per service)

​Security Considerations

​Monitoring & Observability

​Health Checks

​Logs

​Metrics (OpenTelemetry)

​Next Steps

Configuration

Voice Setup

Scaling

Upgrading

Build docs developers (and LLMs) love

Deployment Modes

Core Components

HTTP Services (Node.js + Hono)

WebSocket Gateway (Erlang/OTP)

Frontend Application (React + Electron)

Data Layer

Database Options

Caching & Coordination (Valkey/Redis)

Search Engines

Voice & Video Infrastructure

LiveKit SFU

Message Queue (Microservices Mode)

NATS

Request Flow

Resource Requirements

Monolith Deployment

Microservices Deployment (per service)

Security Considerations

Monitoring & Observability

Health Checks

Logs

Metrics (OpenTelemetry)

Next Steps