# PowerOn Gateway - Session Handling for Horizontal Scaling

## Executive Summary

**Status: ✅ READY FOR HORIZONTAL SCALING**

The PowerOn Gateway uses a stateless, database-backed session architecture that supports horizontal scaling with load balancers. User sessions persist across multiple gateway instances without requiring sticky sessions or shared in-memory storage.

---

## Architecture Overview

### Session Management Approach

**Authentication Method**: JWT tokens stored in httpOnly cookies
- Access token: `auth_token` cookie
- Refresh token: `refresh_token` cookie
- Tokens contain user context (userId, mandateId, sessionId)

**Token Validation**: Database-backed
- All tokens stored in `Token` database table
- Each request validates token against database
- Token status: ACTIVE or REVOKED
- No in-memory session storage (no Redis/Memcached)

**Key Characteristics**:
- ✅ Stateless backend design
- ✅ Database as single source of truth
- ✅ Cookie-based token transmission
- ✅ Independent token validation per instance

---

## Load Balancer Configuration

### Recommended Settings

| Setting | Value | Notes |
|---------|-------|-------|
| **Session Affinity** | **NOT REQUIRED** | Can use round-robin or least-connections |
| **Health Checks** | Standard HTTP | Standard endpoint health checks |
| **Cookie Handling** | Default | Browser handles cookies automatically |
| **Sticky Sessions** | **NOT NEEDED** | Gateway instances are stateless |

### Cookie Configuration

Current cookie settings (configured in code):
- `path="/"` - Available across all paths
- `samesite="strict"` - CSRF protection
- `httponly=True` - XSS protection
- `secure` - Enabled when using HTTPS

**No special load balancer cookie configuration required.**

---

## Deployment Requirements

### Database Configuration

**Requirements for Logical Database**:
- Single logical database instance (shared across all gateway instances)
- Database must be accessible from all gateway instances
- Database must support concurrent connections from multiple instances
- Each gateway instance requires proper database connection pooling
- Database should handle concurrent token validation queries efficiently

**Token Table**: Contains all session state
- Token ID (jti)
- User ID, Session ID, Mandate ID
- Status (ACTIVE/REVOKED)
- Expiration timestamps

### Gateway Instance Configuration

Each gateway instance:
- ✅ Operates independently
- ✅ Validates tokens via database queries
- ✅ No shared state with other instances
- ✅ Can be added/removed without affecting active sessions


### Key Points for Operations

1. ✅ **No sticky sessions required** - Load balancer can distribute requests freely
2. ✅ **Shared logical database required** - All instances access the same database
3. ✅ **Instances are independent** - Can add/remove instances without downtime
4. ✅ **Sessions persist across instances** - Users won't lose sessions during failover

---


*Document prepared for Operations Center*, Patrick Motsch, PowerON AG, 2026-01-11