Microservices Architecture

Helium is built as a collection of focused microservices that cooperate through a shared set of contracts, messaging patterns, and observability tooling. This section introduces the high-level layout of the system, explains how the services interact, and highlights the infrastructure choices that enable the platform to scale for large commercial VPN deployments.

Architectural Goals

• Independent scaling – Each service can be deployed and scaled based on its workload characteristics (API traffic, background jobs, email throughput, etc.).
• Clear boundaries – Services expose well-defined APIs (gRPC, REST, AMQP events) and depend on shared libraries for cross-cutting concerns, ensuring that business logic remains isolated inside its module.
• Operational resiliency – Stateless services, database connection pooling, and message queues allow resilient deployments with graceful failure handling.
• Security by design – Rust, strict processor patterns, and zero shared mutable state within processes prevent memory safety issues and accidental privilege escalations.

Service Topology

The helium-server crate can run in multiple worker modes. Each mode is packaged into its own container image or deployment unit, providing a natural microservice boundary while reusing the same codebase and shared libraries.

These workers are deployed independently and scaled according to throughput requirements. For example, a busy billing period can scale the consumer and cron workers without affecting the gRPC API footprint.

Domain-Oriented Modules

Each domain (Auth, Manage, Telecom, Shop, Market, Notification, Support, Shield, Mailer) is implemented as an independent module under modules/. Modules follow a common layout (entities, services, rpc, hooks, events) as described in the Project Structure Guide. Within the microservices architecture:

• Modules provide service layer processors that encapsulate business logic.
• RPC layers expose the processors through gRPC servers. The GrpcWorker aggregates these services and mounts them behind a single TLS termination point, while keeping module ownership intact.
• Hooks and events enable cross-module interactions without tight coupling, allowing, for instance, the Telecom module to emit usage events consumed by the billing logic in the Manage module.

Communication Patterns

Helium combines synchronous APIs with asynchronous messaging to balance latency and resiliency.

gRPC Contract

• Tonic-generated servers provide strongly typed interfaces for customer-facing and operator APIs.
• A uniform Processor trait ensures every RPC delegate is testable in isolation and can be reused by background workers.
• Service discovery is handled at the infrastructure layer (Kubernetes or Docker Compose) because workers are stateless; clients load-balance using standard mechanisms (Envoy, NGINX, etc.).

REST Facades

• Subscription and webhook workers expose lightweight REST routes via Axum.
• REST APIs reuse the same service processors, ensuring identical business behavior across protocols and simplifying versioning.

Asynchronous Messaging

• RabbitMQ (AMQP) is used to propagate domain events and dispatch background jobs.
• Producers append metadata (correlation IDs, tenant identifiers) to support observability and reliable retries.
• Consumers acknowledge messages only after successful processing, preventing data loss during failures.

Data Management

• PostgreSQL is the system of record. SQLx is used through the DatabaseProcessor abstraction to keep SQL isolated inside entities/ modules and to support compile-time query checking.
• Redis provides ephemeral caches, session storage, and rate limiting. The RedisConnection wrapper from helium-framework manages pooled connections shared by API and worker processes.
• Consistent migrations live in the top-level migrations/ directory and are applied during deployment. Services run with zero shared mutable state; all coordination happens through the database or message queues.

Observability & Operations

• Tracing is initialized in every worker with structured logs and span annotations. This enables distributed tracing across API and background workloads when combined with log collectors.
• Metrics exporters (e.g., Prometheus integration) can be attached at the deployment layer because each worker exposes a predictable Axum/Tonic server endpoint.
• Health probes: gRPC and REST workers perform dependency checks on startup (database, Redis, AMQP). Container orchestrators can use readiness/liveness probes to restart unhealthy instances.

Deployment Model

• Workers are packaged as lightweight containers (<50MB RSS) and designed to be horizontally scalable. Scaling policies are set per worker depending on CPU or queue length metrics.
• Configuration is provided through environment variables (DATABASE_URL, MQ_URL, REDIS_URL, WORK_MODE, etc.), making the platform 12-factor compliant.
• Infrastructure typically consists of:
  • Kubernetes/Docker orchestrating the worker deployments
  • Managed PostgreSQL and Redis services
  • RabbitMQ cluster for messaging
  • Optional CDN or reverse proxy terminating TLS before forwarding requests to gRPC/REST workers.

Extensibility

Adding a new capability follows a repeatable pattern:

1. Create or extend a module under modules/ with the Processor-based service implementation.
2. Expose the functionality via RPC/REST by wiring the service into the relevant worker.
3. Emit domain events or enqueue background jobs when work must be processed asynchronously.
4. Deploy the updated worker image; other workers continue functioning without redeployment because contracts are versioned explicitly.

This approach keeps Helium maintainable while providing the flexibility to grow with complex VPN SaaS requirements.