# Backend Gateway

Version: v1.0.0

## Overview

Backend Gateway is the central access layer between client applications (Tauri, Web, Mobile) and site-specific backend services.

The gateway provides:

* Authentication
* Authorization
* Multi-client routing
* Backend proxying
* Centralized user management
* Secure access through JWT

The goal is to expose a single public endpoint while keeping site backends private behind WireGuard.

---

# Architecture

```text
Tauri/Web App
        │
        ▼
Backend Gateway (VPS)
        │
        ▼
WireGuard Tunnel
        │
        ▼
Site Backend
        │
        ▼
PLC / Modbus / VNC / Local Services
```

Client applications never communicate directly with site backends.

All traffic goes through the gateway.

---

# Technology Stack

* Java 21
* Spring Boot 3
* Spring Security
* JWT (JJWT)
* Flyway
* SQLite
* WireGuard

---

# Database

SQLite database:

```text
./data/backend-gateway.db
```

Schema managed exclusively through Flyway migrations.

Hibernate schema generation is disabled.

```yaml
spring:
  jpa:
    hibernate:
      ddl-auto: none
```

---

# Authentication

Authentication uses username/password credentials.

Endpoint:

```http
POST /auth/login
```

Request:

```json
{
  "username": "admin",
  "password": "admin123"
}
```

Response:

```json
{
  "accessToken": "...",
  "tokenType": "Bearer",
  "userId": 1,
  "clientId": 1,
  "clientName": "dev-local",
  "username": "admin",
  "role": "ADMIN"
}
```

Passwords are stored using BCrypt.

---

# Authorization

Roles currently supported:

```text
ADMIN
CLIENT_USER
```

ADMIN:

* Manage clients
* Manage users
* Access backend proxy

CLIENT_USER:

* Access backend proxy
* No administrative access

---

# JWT

JWT authentication is stateless.

Claims:

```json
{
  "sub": "username",
  "userId": 1,
  "clientId": 1,
  "role": "ADMIN"
}
```

Protected requests require:

```http
Authorization: Bearer <token>
```

---

# Multi-Client Architecture

Each user belongs to a client.

Each client defines a backend endpoint:

```text
client
 └─ backendBaseUrl
```

Example:

```text
Client:
  dev-local

Backend:
  http://10.100.1.2:18450
```

When a user authenticates:

```text
JWT
 └─ clientId
```

The gateway uses the clientId to determine which backend should receive proxied requests.

---

# Backend Proxy

Proxy endpoint:

```http
/api/backend/**
```

Example:

```http
GET /api/backend/actuator/health
```

Gateway flow:

```text
JWT
 └─ clientId

clientId
 └─ backendBaseUrl

backendBaseUrl
 └─ target backend request
```

Users never see backend addresses.

---

# Flyway Migrations

Current migrations:

```text
V1__create_clients.sql
V2__create_users.sql
V3__bootstrap_default_admin.sql
```

Flyway automatically applies migrations on startup.

---

# Bootstrap Administrator

A default administrator is created automatically on a fresh installation.

Default credentials:

```text
Username: admin
Password: admin123
```

IMPORTANT:

Change this password immediately in production.

---

# Environment Variables

Required:

```env
JWT_SECRET=<secret>
```

Optional:

```env
JWT_EXPIRATION_MINUTES=1440
```

Example:

```env
JWT_SECRET=very-long-random-production-secret
JWT_EXPIRATION_MINUTES=1440
```

Configuration:

```yaml
jwt:
  secret: ${JWT_SECRET}
  expiration-minutes: ${JWT_EXPIRATION_MINUTES:1440}
```

---

# VPS Deployment

Required directory:

```text
backend-gateway/
├── data/
├── target/
├── .env
```

Database location:

```text
./data/backend-gateway.db
```

The data directory must exist before startup.

Example:

```bash
mkdir -p data
```

---

# Current Features (v1.0.0)

Implemented:

* JWT Authentication
* BCrypt Passwords
* Role Authorization
* Multi-Client Support
* Client Management
* User Management
* Backend Proxy
* Flyway Migrations
* Bootstrap Admin User
* Environment-Based Secrets
* SQLite Persistence

---

# Planned Features

v1.1

* Change Password Endpoint
* Disable User Endpoint
* Disable Client Endpoint
* Update Client Backend URL

Future

* WebSocket Proxy
* VNC Proxy Support
* Audit Logging
* Refresh Tokens
* User Password Reset
* Client Administration UI

---

# Security Notes

* Never commit .env files.
* Never store JWT secrets in source control.
* Always use HTTPS in production.
* Change bootstrap administrator credentials after installation.
* Keep site backends private behind WireGuard.

---

# Status

Current release:

```text
v1.0.0
```

State:

```text
Production deployable
```