From 95344a03c25d128e17809cbfc161fc95132853d3 Mon Sep 17 00:00:00 2001
From: litoral05 <tiagolitoral05@gmail.com>
Date: Wed, 3 Jun 2026 17:20:33 +0100
Subject: [PATCH] adds readme

---
 README.md | 373 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 373 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4d2eba8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,373 @@
+# 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
+```