Initial commit

2025-11-12 20:22:53 +01:00
commit 43e55f9f18
72 changed files with 3666 additions and 0 deletions
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+/mvnw text eol=lf
+*.cmd text eol=crlf
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,34 @@
+HELP.md
+target/
+.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+/src/main/resources/.env
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
--- a/.mvn/wrapper/maven-wrapper.properties
+++ b/.mvn/wrapper/maven-wrapper.properties
@@ -0,0 +1,2 @@
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
--- a/build-dockerized-native.sh
+++ b/build-dockerized-native.sh
@@ -0,0 +1,5 @@
+set -a
+source ./src/main/resources/.env
+set +a
+./mvnw -Pnative spring-boot:build-image
+
--- a/build-dockerized.sh
+++ b/build-dockerized.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+export $(grep -v '^#' ./src/main/resources/.env | xargs)
+# Build the Docker image
+# to skip tests: -Dmaven.test.skip
+./mvnw spring-boot:build-image
--- a/deploy-image.sh
+++ b/deploy-image.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# Get the latest hydro-backend image tag
+IMAGE_TAG=$(docker images --format '{{.Repository}}:{{.Tag}} {{.CreatedAt}}' | grep '^hydro-backend:' | sort -k2 -r | head -n1 | awk '{print $1}')
+
+# Save the Docker image to a tar file
+docker save "$IMAGE_TAG" > /tmp/hydro-backend.tar
+
+# Copy the tar file to the remote server
+scp /tmp/hydro-backend.tar admin@netoasis.app:/home/admin/hydro-backend.tar
+
+# SSH into the remote server and execute commands with a pseudo-terminal
+ssh -t admin@netoasis.app "docker load -i /home/admin/hydro-backend.tar && cd /home/admin/ && docker-compose up"
--- a/hydro-backend.tar
+++ b/hydro-backend.tar
--- a/295
+++ b/295
@@ -0,0 +1,295 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Apache Maven Wrapper startup batch script, version 3.3.3
+#
+# Optional ENV vars
+# -----------------
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
+#   MVNW_REPOURL - repo url base for downloading maven distribution
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
+# ----------------------------------------------------------------------------
+
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
+
+# OS specific support.
+native_path() { printf %s\\n "$1"; }
+case "$(uname)" in
+CYGWIN* | MINGW*)
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
+  native_path() { cygpath --path --windows "$1"; }
+  ;;
+esac
+
+# set JAVACMD and JAVACCMD
+set_java_home() {
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
+  if [ -n "${JAVA_HOME-}" ]; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
+      # IBM's JDK on AIX uses strange locations for the executables
+      JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
+    else
+      JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
+    fi
+  else
+    JAVACMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
+
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
+      return 1
+    fi
+  fi
+}
+
+# hash string like Java String::hashCode
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
+  done
+  printf %x\\n $h
+}
+
+verbose() { :; }
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
+
+die() {
+  printf %s\\n "$1" >&2
+  exit 1
+}
+
+trim() {
+  # MWRAPPER-139:
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
+}
+
+scriptDir="$(dirname "$0")"
+scriptName="$(basename "$0")"
+
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
+while IFS="=" read -r key value; do
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
+  esac
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+
+case "${distributionUrl##*/}" in
+maven-mvnd-*bin.*)
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<-END
+	public class Downloader extends java.net.Authenticator
+	{
+	  protected java.net.PasswordAuthentication getPasswordAuthentication()
+	  {
+	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+	  }
+	  public static void main( String[] args ) throws Exception
+	  {
+	    setDefault( new Downloader() );
+	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+	  }
+	}
+	END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  elif command -v shasum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  else
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  fi
+  if [ $distributionSha256Result = false ]; then
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
+    exit 1
+  fi
+fi
+
+# unzip and move
+if command -v unzip >/dev/null; then
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
+else
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
+fi
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+actualDistributionDir=""
+
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if [ -z "$actualDistributionDir" ]; then
+  # enable globbing to iterate over items
+  set +f
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
+    if [ -d "$dir" ]; then
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"
--- a/mvnw.cmd
+++ b/mvnw.cmd
@@ -0,0 +1,189 @@
+<# : batch portion
+@REM ----------------------------------------------------------------------------
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+@REM
+@REM    http://www.apache.org/licenses/LICENSE-2.0
+@REM
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+@REM ----------------------------------------------------------------------------
+
+@REM ----------------------------------------------------------------------------
+@REM Apache Maven Wrapper startup batch script, version 3.3.3
+@REM
+@REM Optional ENV vars
+@REM   MVNW_REPOURL - repo url base for downloading maven distribution
+@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
+@REM ----------------------------------------------------------------------------
+
+@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
+@SET __MVNW_CMD__=
+@SET __MVNW_ERROR__=
+@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
+@SET PSModulePath=
+@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
+  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
+)
+@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
+@SET __MVNW_PSMODULEP_SAVE=
+@SET __MVNW_ARG0_NAME__=
+@SET MVNW_USERNAME=
+@SET MVNW_PASSWORD=
+@IF NOT "%__MVNW_CMD__%"=="" ("%__MVNW_CMD__%" %*)
+@echo Cannot start maven from wrapper >&2 && exit /b 1
+@GOTO :EOF
+: end batch / begin powershell #>
+
+$ErrorActionPreference = "Stop"
+if ($env:MVNW_VERBOSE -eq "true") {
+  $VerbosePreference = "Continue"
+}
+
+# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
+$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
+if (!$distributionUrl) {
+  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+}
+
+switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
+  "maven-mvnd-*" {
+    $USE_MVND = $true
+    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
+    $MVN_CMD = "mvnd.cmd"
+    break
+  }
+  default {
+    $USE_MVND = $false
+    $MVN_CMD = $script -replace '^mvnw','mvn'
+    break
+  }
+}
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+if ($env:MVNW_REPOURL) {
+  $MVNW_REPO_PATTERN = if ($USE_MVND -eq $False) { "/org/apache/maven/" } else { "/maven/mvnd/" }
+  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace "^.*$MVNW_REPO_PATTERN",'')"
+}
+$distributionUrlName = $distributionUrl -replace '^.*/',''
+$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
+
+$MAVEN_M2_PATH = "$HOME/.m2"
+if ($env:MAVEN_USER_HOME) {
+  $MAVEN_M2_PATH = "$env:MAVEN_USER_HOME"
+}
+
+if (-not (Test-Path -Path $MAVEN_M2_PATH)) {
+    New-Item -Path $MAVEN_M2_PATH -ItemType Directory | Out-Null
+}
+
+$MAVEN_WRAPPER_DISTS = $null
+if ((Get-Item $MAVEN_M2_PATH).Target[0] -eq $null) {
+  $MAVEN_WRAPPER_DISTS = "$MAVEN_M2_PATH/wrapper/dists"
+} else {
+  $MAVEN_WRAPPER_DISTS = (Get-Item $MAVEN_M2_PATH).Target[0] + "/wrapper/dists"
+}
+
+$MAVEN_HOME_PARENT = "$MAVEN_WRAPPER_DISTS/$distributionUrlNameMain"
+$MAVEN_HOME_NAME = ([System.Security.Cryptography.SHA256]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
+$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
+
+if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
+  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
+  exit $?
+}
+
+if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
+  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
+}
+
+# prepare tmp dir
+$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
+$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
+$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
+trap {
+  if ($TMP_DOWNLOAD_DIR.Exists) {
+    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+  }
+}
+
+New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
+
+# Download and Install Apache Maven
+Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+Write-Verbose "Downloading from: $distributionUrl"
+Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+$webclient = New-Object System.Net.WebClient
+if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
+  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
+}
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
+if ($distributionSha256Sum) {
+  if ($USE_MVND) {
+    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
+  }
+  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
+  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
+    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
+  }
+}
+
+# unzip and move
+Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+$actualDistributionDir = ""
+
+# First try the expected directory name (for regular distributions)
+$expectedPath = Join-Path "$TMP_DOWNLOAD_DIR" "$distributionUrlNameMain"
+$expectedMvnPath = Join-Path "$expectedPath" "bin/$MVN_CMD"
+if ((Test-Path -Path $expectedPath -PathType Container) -and (Test-Path -Path $expectedMvnPath -PathType Leaf)) {
+  $actualDistributionDir = $distributionUrlNameMain
+}
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if (!$actualDistributionDir) {
+  Get-ChildItem -Path "$TMP_DOWNLOAD_DIR" -Directory | ForEach-Object {
+    $testPath = Join-Path $_.FullName "bin/$MVN_CMD"
+    if (Test-Path -Path $testPath -PathType Leaf) {
+      $actualDistributionDir = $_.Name
+    }
+  }
+}
+
+if (!$actualDistributionDir) {
+  Write-Error "Could not find Maven distribution directory in extracted archive"
+}
+
+Write-Verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+Rename-Item -Path "$TMP_DOWNLOAD_DIR/$actualDistributionDir" -NewName $MAVEN_HOME_NAME | Out-Null
+try {
+  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
+} catch {
+  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
+    Write-Error "fail to move MAVEN_HOME"
+  }
+} finally {
+  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+}
+
+Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
--- a/pom.xml
+++ b/pom.xml
@@ -0,0 +1,177 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+	<parent>
+		<groupId>org.springframework.boot</groupId>
+		<artifactId>spring-boot-starter-parent</artifactId>
+		<version>3.5.5</version>
+		<relativePath/> <!-- lookup parent from repository -->
+	</parent>
+	<groupId>dev.ivfrost</groupId>
+	<artifactId>hydro-backend</artifactId>
+	<version>0.0.1-SNAPSHOT</version>
+	<name>hydro-backend</name>
+	<description>Backend API for Hydro UI: user accounts, device linking, QR code verification</description>
+    <properties>
+        <java.version>17</java.version>
+        <spring-cloud.version>2025.0.0</spring-cloud.version>
+    </properties>
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.cloud</groupId>
+                <artifactId>spring-cloud-dependencies</artifactId>
+                <version>${spring-cloud.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-data-jpa</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-security</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-web</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.postgresql</groupId>
+			<artifactId>postgresql</artifactId>
+			<scope>runtime</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-test</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.springframework.security</groupId>
+			<artifactId>spring-security-test</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<!-- Extra dependencies -->
+		<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core -->
+		<dependency>
+			<groupId>com.fasterxml.jackson.core</groupId>
+			<artifactId>jackson-core</artifactId>
+			<version>2.20.0</version>
+		</dependency>
+        <!-- https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-openfeign -->
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-starter-openfeign</artifactId>
+        </dependency>
+		<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+			<version>1.18.38</version>
+		</dependency>
+		<!-- https://mvnrepository.com/artifact/org.springframework.security/spring-security-crypto -->
+		<dependency>
+			<groupId>org.springframework.security</groupId>
+			<artifactId>spring-security-crypto</artifactId>
+			<version>6.5.3</version>
+		</dependency>
+		<!-- https://mvnrepository.com/artifact/jakarta.validation/jakarta.validation-api -->
+		<dependency>
+			<groupId>jakarta.validation</groupId>
+			<artifactId>jakarta.validation-api</artifactId>
+			<version>3.0.2</version>
+		</dependency>
+		<!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-validation -->
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-validation</artifactId>
+		</dependency>
+        <!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.9</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-mail</artifactId>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-api -->
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-api</artifactId>
+            <version>0.12.6</version>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.auth0/java-jwt -->
+        <dependency>
+            <groupId>com.auth0</groupId>
+            <artifactId>java-jwt</artifactId>
+            <version>4.5.0</version>
+        </dependency>
+        <!-- https://mvnrepository.com/artifact/com.bucket4j/bucket4j_jdk17-core -->
+        <dependency>
+            <groupId>com.bucket4j</groupId>
+            <artifactId>bucket4j_jdk17-core</artifactId>
+            <version>8.15.0</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.vladmihalcea</groupId>
+            <artifactId>hibernate-types-60</artifactId>
+            <version>2.21.1</version>
+        </dependency>
+        <dependency>
+            <groupId>org.hibernate.orm</groupId>
+            <artifactId>hibernate-core</artifactId>
+        </dependency>
+	</dependencies>
+	<build>
+		<plugins>
+            <plugin>
+                <groupId>org.graalvm.buildtools</groupId>
+                <artifactId>native-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.11.0</version>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                            <version>1.18.38</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+		</plugins>
+	</build>
+    <profiles>
+        <profile>
+            <id>native</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.springframework.boot</groupId>
+                        <artifactId>spring-boot-maven-plugin</artifactId>
+                        <configuration>
+                            <image>
+                                <builder>paketobuildpacks/builder-jammy-buildpackless-tiny</builder>
+                                <buildpacks>
+                                    <buildpack>paketobuildpacks/oracle</buildpack>
+                                    <buildpack>paketobuildpacks/java-native-image</buildpack>
+                                </buildpacks>
+                            </image>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+</project>
--- a/src/main/java/dev/ivfrost/hydro_backend/HydroBackendApplication.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/HydroBackendApplication.java
@@ -0,0 +1,18 @@
+package dev.ivfrost.hydro_backend;
+
+import dev.ivfrost.hydro_backend.config.MyRuntimeHints;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.openfeign.EnableFeignClients;
+
+import org.springframework.context.annotation.ImportRuntimeHints;
+
+@SpringBootApplication
+@EnableFeignClients
+@ImportRuntimeHints(MyRuntimeHints.class)
+public class HydroBackendApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(HydroBackendApplication.class, args);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/config/MyRuntimeHints.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/config/MyRuntimeHints.java
@@ -0,0 +1,51 @@
+package dev.ivfrost.hydro_backend.config;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import org.springframework.aot.hint.MemberCategory;
+import org.springframework.aot.hint.RuntimeHintsRegistrar;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.ivfrost.hydro_backend.dto.UserRegisterRequest;
+import dev.ivfrost.hydro_backend.dto.UserLoginRequest;
+import dev.ivfrost.hydro_backend.dto.DeviceLinkRequest;
+import dev.ivfrost.hydro_backend.dto.DeviceProvisionRequest;
+import org.springframework.aot.hint.TypeReference;
+
+// Specify to Spring AOT that these classes will be need to be accessed via reflection
+public class MyRuntimeHints implements RuntimeHintsRegistrar {
+    @Override
+    public void registerHints(org.springframework.aot.hint.RuntimeHints hints, ClassLoader classLoader) {
+        hints.reflection().registerType(JsonNode.class);
+        hints.reflection().registerType(ObjectMapper.class);
+        hints.reflection().registerType(
+                TypeReference.of("org.springframework.core.annotation.TypeMappedAnnotation[]"),
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS
+        );
+
+        // Register DTOs for reflection
+        hints.reflection().registerType(DeviceLinkRequest.class,
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
+                MemberCategory.INVOKE_DECLARED_METHODS,
+                MemberCategory.DECLARED_FIELDS);
+        hints.reflection().registerType(DeviceProvisionRequest.class,
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
+                MemberCategory.INVOKE_DECLARED_METHODS,
+                MemberCategory.DECLARED_FIELDS);
+        hints.reflection().registerType(UserRegisterRequest.class,
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
+                MemberCategory.INVOKE_DECLARED_METHODS,
+                MemberCategory.DECLARED_FIELDS);
+        hints.reflection().registerType(UserLoginRequest.class,
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
+                MemberCategory.INVOKE_DECLARED_METHODS,
+                MemberCategory.DECLARED_FIELDS);
+
+        // Validation of individual entity fields with reflection
+        hints.reflection().registerType(
+                User.class,
+                MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
+                MemberCategory.INVOKE_DECLARED_METHODS,
+                MemberCategory.DECLARED_FIELDS
+        );
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/config/OpenApiConfig.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/config/OpenApiConfig.java
@@ -0,0 +1,27 @@
+package dev.ivfrost.hydro_backend.config;
+
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.security.SecurityScheme;
+import io.swagger.v3.oas.annotations.servers.Server;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
+
+@Configuration
+@OpenAPIDefinition(
+    info = @Info(title = "Hydro Backend API", version = "v1"),
+    security = @SecurityRequirement(name = "bearerAuth"),
+    servers = {@Server(url = "${server.servlet.context-path}", description = "Default Server URL")}
+)
+@SecurityScheme(
+    name = "bearerAuth",
+    type = SecuritySchemeType.HTTP,
+    scheme = "bearer",
+    bearerFormat = "JWT"
+)
+@EnableMethodSecurity(prePostEnabled = true)
+public class OpenApiConfig {
+}
+
--- a/src/main/java/dev/ivfrost/hydro_backend/config/RateLimitConfig.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/config/RateLimitConfig.java
@@ -0,0 +1,17 @@
+package dev.ivfrost.hydro_backend.config;
+
+import io.github.bucket4j.Bucket;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+
+@Configuration
+public class RateLimitConfig {
+
+    @Bean
+    public ConcurrentMap<String, Bucket> buckets() {
+        return new ConcurrentHashMap<>();
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/config/SecurityConfig.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/config/SecurityConfig.java
@@ -0,0 +1,128 @@
+package dev.ivfrost.hydro_backend.config;
+
+import dev.ivfrost.hydro_backend.security.JWTFilter;
+import dev.ivfrost.hydro_backend.service.MyUserDetailsService;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.AllArgsConstructor;
+import lombok.NonNull;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+import static org.springframework.security.config.Customizer.withDefaults;
+
+@AllArgsConstructor
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    private final MyUserDetailsService userDetailsService;
+    private final JWTFilter jwtFilter;
+    private final String[] allowedOrigins = {
+            "https://netoasis.app",
+            "87.223.194.213",
+            "http://localhost:5173"
+    };
+
+    @Bean
+    public SecurityFilterChain securityFilterChain(final HttpSecurity http) throws Exception {
+        System.out.println("Configuring security filter chain");
+        http
+                .csrf(AbstractHttpConfigurer::disable)
+                .httpBasic(AbstractHttpConfigurer::disable)
+                .cors(withDefaults())
+                .addFilterBefore(this.jwtFilter, UsernamePasswordAuthenticationFilter.class)
+                .authorizeHttpRequests(req -> req
+                        .requestMatchers(
+                                "/docs/",
+                                "/docs/**",
+                                "/v1/api/**",
+                                "/v2/api-docs",
+                                "/v3/api-docs",
+                                "/v3/api-docs/**",
+                                "/swagger-resources",
+                                "/swagger-resources/**",
+                                "/configuration/ui",
+                                "/configuration/security",
+                                "/swagger-ui/**",
+                                "/webjars/**",
+                                "/swagger-ui.html",
+                                "/v1/users",
+                                "/v1/users/auth",
+                                "/v1/users/password/reset",
+                                "/v1/validation",
+                                "/v1/validation/**",
+                                "/v1/health"
+                        ).permitAll()
+                        .requestMatchers(
+                                "/v1/me/**",
+                                "/v1/users/**",
+                                "/v1/devices/**"
+                        ).hasAnyRole("USER", "ADMIN")
+                        .anyRequest().authenticated()
+                )
+                .userDetailsService(this.userDetailsService)
+                .exceptionHandling(e -> e.authenticationEntryPoint((request, response, authException) ->
+                        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized")))
+                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
+        System.out.println("Security filter chain configured");
+        return http.build();
+    }
+
+    // Authentication manager bean to be used in AuthController
+    @Bean
+    public AuthenticationManager authenticationManager(final AuthenticationConfiguration authenticationConfiguration) throws Exception {
+        return authenticationConfiguration.getAuthenticationManager();
+    }
+
+    // Password encoder bean (BCrypt)
+    @Bean
+    public PasswordEncoder passwordEncoder() {
+        return new BCryptPasswordEncoder();
+    }
+
+    // CORS configuration
+    @Bean
+    public WebMvcConfigurer corsConfigurer() {
+        return new WebMvcConfigurer() {
+            @Override
+            public void addCorsMappings(@NonNull final CorsRegistry registry) {
+                registry.addMapping("/v1/validation")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/validation/**")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/api/**")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/users")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/users/**")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/me/**")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/devices/**")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+                registry.addMapping("/v1/health")
+                        .allowedOrigins(allowedOrigins)
+                        .allowedMethods("*");
+            }
+        };
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/AuthController.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/AuthController.java
@@ -0,0 +1,86 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.service.UserService;
+import dev.ivfrost.hydro_backend.util.RateLimitUtils;
+import io.github.bucket4j.Bucket;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.Valid;
+import lombok.AllArgsConstructor;
+import org.springdoc.webmvc.core.service.RequestService;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Optional;
+
+@Tag(name = "User Authentication", description = "API endpoints for user authentication")
+@AllArgsConstructor
+@RestController
+@RequestMapping("/v1/")
+public class AuthController {
+
+    private final UserService userService;
+    private final RateLimitUtils rateLimitUtils;
+    private final RequestService requestService;
+
+    //======= NON-AUTHENTICATED USERS ENDPOINTS =======//
+
+    // Data provision
+    @Operation(
+            summary = "Register a new user",
+            description = "Creates a new user account."
+    )
+    @PostMapping("/users")
+    public ResponseEntity<ApiResponse<UserRegisterResponse>> registerUser(
+            @Valid @RequestBody UserRegisterRequest userRegisterRequest, HttpServletRequest req) {
+
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(5)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS, "Too many requests - rate limit exceeded", null));
+        }
+
+        UserRegisterResponse recoveryCodes = userService.addUser(userRegisterRequest);
+        return ResponseEntity
+                .status(HttpStatus.CREATED)
+                .body(ApiResponse.build(HttpStatus.CREATED, "User registered successfully", recoveryCodes));
+    }
+
+    @Operation(
+            summary = "Authenticate user",
+            description = "Authenticates a user and returns a JWT token."
+    )
+    @PostMapping("/users/auth")
+    public ResponseEntity<ApiResponse<AuthResponse>> authenticateUser(
+            @Valid @RequestBody UserLoginRequest userLoginRequest, HttpServletRequest req) {
+
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(2)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS, "", null));
+        }
+
+        AuthResponse authResponse = userService.authenticateUser(userLoginRequest);
+        ApiResponse<AuthResponse> response = ApiResponse.build(HttpStatus.OK, "User authenticated successfully", authResponse);
+        return ResponseEntity.ok(response);
+    }
+
+    @Operation(
+            summary = "Refresh JWT token",
+            description = "Refreshes the JWT token for an authenticated user."
+    )
+    @PostMapping("/users/refresh")
+    public ResponseEntity<ApiResponse<AuthResponse>> refreshToken() {
+        AuthResponse authResponse = userService.refreshTokens();
+        ApiResponse<AuthResponse> response = ApiResponse.build(HttpStatus.OK, "Token refreshed successfully", authResponse);
+        return ResponseEntity.ok(response);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/DeviceAuthController.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/DeviceAuthController.java
@@ -0,0 +1,45 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import dev.ivfrost.hydro_backend.dto.ApiResponse;
+import dev.ivfrost.hydro_backend.dto.DeviceLinkRequest;
+import dev.ivfrost.hydro_backend.dto.MqttCredentialsResponse;
+import dev.ivfrost.hydro_backend.service.DeviceService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.AllArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@AllArgsConstructor
+@Tag(name = "Device Authentication", description = "API endpoints for proving device ownership and getting credentials")
+@RestController
+@RequestMapping("/v1")
+public class DeviceAuthController {
+
+    private final DeviceService deviceService;
+
+    @Operation(
+            summary = "Link device to authenticated user",
+            description = "Links a device to the currently authenticated user using the device's ownership hash."
+    )
+    @PostMapping("/me/devices/link")
+    public ResponseEntity<ApiResponse<Void>> linkDevice(@RequestParam String hash) {
+        deviceService.linkDevice(new DeviceLinkRequest(hash));
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device linked to user successfully", null));
+    }
+
+    @Operation(
+            summary = "Get MQTT credentials",
+            description = "Retrieves MQTT credentials for the currently authenticated user."
+    )
+    @GetMapping("/me/devices/credentials")
+    public ResponseEntity<ApiResponse<MqttCredentialsResponse>> getMqttCredentials() {
+        MqttCredentialsResponse credentials = deviceService.getMqttCredentials();
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "MQTT credentials retrieved successfully", credentials));
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/DeviceController.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/DeviceController.java
@@ -0,0 +1,149 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.service.DeviceService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.AllArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+@Tag(name = "Device Management", description = "API endpoints for managing devices")
+@AllArgsConstructor
+@RestController
+@RequestMapping("/v1")
+public class DeviceController {
+
+    private final DeviceService deviceService;
+
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+        summary = "Link device to user by ID (Admin only)",
+        description = "Links a device to a specific user by their unique ID using the device's ownership hash. Access restricted to administrators."
+    )
+    @PostMapping("/users/{userId}/devices/link")
+    public ResponseEntity<ApiResponse<Void>> linkDeviceById(
+            @RequestBody @Valid DeviceLinkRequest linkDeviceRequest,
+            @PathVariable Long userId) {
+
+        deviceService.linkDevice(linkDeviceRequest, userId);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device linked to user successfully", null));
+    }
+
+    @Operation(
+            summary = "Unlink device from authenticated user",
+            description = "Unlinks a device from the currently authenticated user using the device's unique ID."
+    )
+    @DeleteMapping("/me/devices/{deviceId}/unlink")
+    public ResponseEntity<ApiResponse<Void>> unlinkDevice(@PathVariable Long deviceId) {
+        deviceService.unlinkDevice(deviceId);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device unlinked from user successfully", null));
+    }
+
+    @Operation(
+        summary = "Get linked devices",
+        description = "Retrieves all devices linked to the currently authenticated user."
+    )
+    @GetMapping("/me/devices")
+    public ResponseEntity<ApiResponse<List<DeviceResponse>>> getUserDevices() {
+        List<DeviceResponse> response = deviceService.getUserDevices();
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Devices retrieved successfully", response));
+    }
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @GetMapping("/users/{userId}/devices")
+    @Operation(
+            summary = "Get devices by user ID (Admin only)",
+            description = "Retrieves all devices linked to a specific user by their unique ID."
+    )
+    public ResponseEntity<ApiResponse<List<DeviceResponse>>> getUserDevicesById(@PathVariable Long userId) {
+        List<DeviceResponse> response = deviceService.getUserDevicesById(userId);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Devices retrieved successfully", response));
+    }
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+            summary = "Get all provisioned devices (Admin only)",
+            description = "Retrieves all devices provisioned in the system."
+    )
+    @GetMapping("/devices")
+    public ResponseEntity<ApiResponse<List<DeviceResponse>>> getAllDevices() {
+        List<DeviceResponse> response = deviceService.getAllDevices();
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "All devices retrieved successfully", response));
+    }
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+        summary = "Provision new device (Admin only)",
+        description = "Provisions a new device in the system."
+    )
+    @PostMapping("/devices")
+    public ResponseEntity<ApiResponse<DeviceResponse>> provisionDevice(@RequestBody @Valid DeviceProvisionRequest req) {
+        DeviceResponse device = deviceService.provisionDevice(req);
+        return ResponseEntity
+                .status(HttpStatus.CREATED)
+                .body(ApiResponse.build(HttpStatus.CREATED, "Device provisioned successfully", device));
+    }
+
+    @Operation(
+            summary = "Update order or user-defined name of a device",
+            description = "Updates the display order or user-defined name of a device linked to the authenticated user."
+    )
+    @PutMapping("/me/devices/{deviceId}")
+    public ResponseEntity<ApiResponse<DeviceResponse>> updateUserDeviceById(
+            @PathVariable Long deviceId,
+            @RequestBody @Valid DeviceUpdateRequest req) {
+
+        DeviceResponse updatedDevice = deviceService.updateUserDeviceById(deviceId, req);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device updated successfully", updatedDevice));
+    }
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+        summary = "Update device by ID (Admin only)",
+        description = "Updates the details of a device by its unique ID."
+    )
+    @PutMapping("/devices/{deviceId}")
+    public ResponseEntity<ApiResponse<DeviceResponse>> updateDeviceById(
+            @PathVariable Long deviceId,
+            @RequestBody @Valid DeviceUpdateRequest req,
+            @RequestParam String technicalName,
+            @RequestParam String firmware) {
+
+        DeviceResponse updatedDevice = deviceService.updateDeviceById(deviceId, req, technicalName, firmware);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device updated successfully", updatedDevice));
+    }
+
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+        summary = "Delete device by ID (Admin only)",
+        description = "Deletes a device from the system by its unique ID."
+    )
+    @DeleteMapping("/devices/{deviceId}")
+    public ResponseEntity<ApiResponse<Void>> deleteDeviceById(@PathVariable Long deviceId) {
+        deviceService.deleteDeviceById(deviceId);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Device deleted successfully", null));
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/GlobalExceptionHandler.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/GlobalExceptionHandler.java
@@ -0,0 +1,113 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import com.auth0.jwt.exceptions.JWTCreationException;
+import com.auth0.jwt.exceptions.JWTVerificationException;
+import dev.ivfrost.hydro_backend.dto.ApiResponse;
+import dev.ivfrost.hydro_backend.exception.*;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.time.LocalDateTime;
+import java.util.HashMap;
+import java.util.Map;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(UserDeletedException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleUserDeletedException(UserDeletedException ex) {
+        return ResponseEntity.status(HttpStatus.FORBIDDEN).body(
+                ApiResponse.build(HttpStatus.FORBIDDEN, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(UserNotFoundException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleUserNotFoundException(UserNotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(
+                ApiResponse.build(HttpStatus.NOT_FOUND, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(UserNotAuthenticatedException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleUserNotAuthenticatedException(UserNotAuthenticatedException ex) {
+        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(
+                ApiResponse.build(HttpStatus.UNAUTHORIZED, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(TokenNotFoundException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleTokenNotFoundException(TokenNotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(
+                ApiResponse.build(HttpStatus.NOT_FOUND, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(ExpiredVerificationToken.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleExpiredVerificationToken(ExpiredVerificationToken ex) {
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
+                ApiResponse.build(HttpStatus.BAD_REQUEST, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(JWTCreationException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleJWTCreationException(JWTCreationException ex) {
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(
+                ApiResponse.build(HttpStatus.INTERNAL_SERVER_ERROR, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(JWTVerificationException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>>  handleJWTVerificationException(JWTVerificationException ex) {
+        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(
+                ApiResponse.build(HttpStatus.UNAUTHORIZED, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(DeviceLinkException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleDeviceLinkException(DeviceLinkException ex) {
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
+                ApiResponse.build(HttpStatus.BAD_REQUEST, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(DeviceFetchException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleDeviceFetchException(DeviceFetchException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(
+                ApiResponse.build(HttpStatus.NOT_FOUND, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ApiResponse<Object>> handleValidationException(MethodArgumentNotValidException ex) {
+        // Collect field errors into a map
+        Map<String, String> errors = new HashMap<>();
+        ex.getBindingResult().getFieldErrors().forEach(error ->
+            errors.put(error.getField(), error.getDefaultMessage())
+        );
+        String message = "Validation failed for one or more fields.";
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
+                ApiResponse.build(HttpStatus.BAD_REQUEST, message, errors)
+        );
+    }
+
+    @ExceptionHandler(RecoveryTokenNotFoundException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleRecoveryCodeNotFoundException(
+            RecoveryTokenNotFoundException ex) {
+
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(
+                ApiResponse.build(HttpStatus.NOT_FOUND, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+
+    @ExceptionHandler(RecoveryTokenMismatchException.class)
+    public ResponseEntity<ApiResponse<LocalDateTime>> handleRecoveryCodeMismatchException(
+            RecoveryTokenMismatchException ex) {
+
+        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(
+                ApiResponse.build(HttpStatus.BAD_REQUEST, ex.getMessage(), LocalDateTime.now())
+        );
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/UserController.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/UserController.java
@@ -0,0 +1,153 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.entity.User;
+import dev.ivfrost.hydro_backend.service.UserService;
+import dev.ivfrost.hydro_backend.util.RateLimitUtils;
+import io.github.bucket4j.Bucket;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.Valid;
+import lombok.AllArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.Optional;
+
+@Tag(name = "User Management", description = "API endpoints for managing users")
+@AllArgsConstructor
+@RestController
+@RequestMapping("/v1")
+public class UserController {
+
+    private final UserService userService;
+    private final RateLimitUtils rateLimitUtils;
+
+    //======= NON-AUTHENTICATED USERS ENDPOINTS =======//
+
+    // Data modification
+    @Operation(
+            summary = "Reset user password",
+            description = "Resets the user's password using one of the recovery codes provided on registration"
+    )
+    @PutMapping("/users/password/reset")
+    public ResponseEntity<ApiResponse<Void>> resetPassword(
+            @Valid @RequestBody PasswordResetRequest passwordResetConfirmRequest, HttpServletRequest req) {
+
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(3)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS, "", null));
+        }
+        userService.resetPassword(passwordResetConfirmRequest);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "Password has been reset successfully", null));
+    }
+
+
+    //======= AUTHENTICATED USERS ENDPOINTS =======//
+
+    // Data retrieval
+    @Operation(
+            summary = "Get authenticated user's profile",
+            description = "Retrieves the profile of the currently authenticated user."
+    )
+    @GetMapping("/me")
+    public ResponseEntity<ApiResponse<UserResponse>> getCurrentUserProfile() {
+        UserResponse userResponse = userService.getCurrentUserProfile();
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "User profile retrieved successfully", userResponse));
+    }
+
+    // Data modification
+    @Operation(
+            summary = "Update user's account settings",
+            description = "Updates the account settings of the currently authenticated user."
+    )
+    @PutMapping("/me")
+    public ResponseEntity<ApiResponse<UserResponse>> updateCurrentUser(
+            @Valid @RequestBody UserUpdateRequest userUpdateRequest, HttpServletRequest req) {
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(1)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS,
+                            "", null));
+        }
+        UserResponse updatedUser = userService.updateCurrentUser(userUpdateRequest);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "User profile updated successfully", updatedUser));
+    }
+
+    // Data removal
+    @Operation(
+            summary = "Delete authenticated user",
+            description = "Deletes the currently authenticated user (soft delete)."
+    )
+    @DeleteMapping("/me")
+    public ResponseEntity<ApiResponse<Void>> deleteCurrentUser(HttpServletRequest req) {
+
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(2)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS,
+                            "", null));
+        }
+        userService.deleteCurrentUser();
+        return ResponseEntity
+                .status(HttpStatus.NO_CONTENT)
+                .body(ApiResponse.build(HttpStatus.NO_CONTENT, "User deleted successfully", null));
+    }
+
+    //======= ADMIN-ONLY ENDPOINTS =======//
+
+    // Data provision
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+            summary = "Register a new user (Admin only)",
+            description = "Creates a new user account at admin's discretion and returns a JWT token. Allows setting user role."
+    )
+    @PostMapping("/users/new")
+    public ResponseEntity<ApiResponse<Void>> registerUsersAdmin(
+            @Valid @RequestBody UserRegisterRequest req, @RequestParam(required = false) User.Role role) {
+        return ResponseEntity
+                .status(HttpStatus.CREATED)
+                .body(ApiResponse.build(HttpStatus.CREATED, "User registered successfully", null));
+    }
+
+    // Data retrieval
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+            summary = "Get user profile by ID (Admin only)",
+            description = "Retrieves a user profile by ID."
+    )
+    @GetMapping("/users/{userId}")
+    public ResponseEntity<ApiResponse<UserResponse>> getUserProfileById(@PathVariable Long userId) {
+        UserResponse userResponse = userService.getUserProfileById(userId);
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(ApiResponse.build(HttpStatus.OK, "User profile retrieved successfully", userResponse));
+    }
+
+    // Data removal
+    @PreAuthorize("hasRole('ADMIN')")
+    @Operation(
+            summary = "Delete user by ID (Admin only)",
+            description = "Deletes a user by ID (soft delete)."
+    )
+    @DeleteMapping("/users/{userId}")
+    public ResponseEntity<ApiResponse<Void>> deleteUserById(@PathVariable Long userId) {
+        userService.deleteUserById(userId);
+        return ResponseEntity
+                .status(HttpStatus.NO_CONTENT)
+                .body(ApiResponse.build(HttpStatus.NO_CONTENT, "User deleted successfully", null));
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/controller/ValidationController.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/controller/ValidationController.java
@@ -0,0 +1,123 @@
+package dev.ivfrost.hydro_backend.controller;
+
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.repository.UserTokenRepository;
+import dev.ivfrost.hydro_backend.service.UserService;
+import dev.ivfrost.hydro_backend.service.UserTokenService;
+import dev.ivfrost.hydro_backend.util.RateLimitUtils;
+import dev.ivfrost.hydro_backend.util.ValidationUtils;
+import io.github.bucket4j.Bucket;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import lombok.AllArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+@Tag(name = "Validation ", description = "API endpoints for validating data")
+@AllArgsConstructor
+@RequestMapping("/v1/validation")
+@RestController
+public class ValidationController {
+
+    private final UserTokenRepository userTokenRepository;
+    ValidationUtils validationUtils;
+    HashMap<String, Bucket> buckets;
+    RateLimitUtils rateLimitUtils;
+    UserService userService;
+    UserTokenService userTokenService;
+
+    @Operation(summary = "Get validation rules for a specific class")
+    @GetMapping("/rules")
+    public ResponseEntity<?> getClassValidationRules(@RequestParam String className, HttpServletRequest req) {
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(1)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS, "", null));
+        }
+
+        Map<String, Object> rules;
+        String message;
+        switch (className) {
+            case "UserRegisterRequest" -> {
+                rules = validationUtils.getClassValidationRules(UserRegisterRequest.class);
+                message = "User register validation rules";
+            }
+            case "UserLoginRequest" -> {
+                rules = validationUtils.getClassValidationRules(UserLoginRequest.class);
+                message = "User login validation rules";
+            }
+            case "DeviceProvisionRequest" -> {
+                rules = validationUtils.getClassValidationRules(DeviceProvisionRequest.class);
+                message = "Device provision validation rules";
+            }
+            case "DeviceLinkRequest" -> {
+                rules = validationUtils.getClassValidationRules(DeviceLinkRequest.class);
+                message = "Device link validation rules";
+            }
+            default -> {
+                return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                        .body(ApiResponse.build(HttpStatus.BAD_REQUEST, "Invalid field", null));
+            }
+        }
+        return ResponseEntity.ok(ApiResponse.build(HttpStatus.OK, message, rules));
+    }
+
+    @Operation(summary = "Get availability of a username or email")
+    @GetMapping("/availability")
+    public ResponseEntity<?> checkUsernameEmailAvailability(
+            @RequestParam(required = false) String username,
+            @RequestParam(required = false) String email,
+            HttpServletRequest req) {
+
+        if (username == null && email == null) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(ApiResponse.build(HttpStatus.BAD_REQUEST, "Either username or email must be provided", null));
+        }
+        if (username != null && email != null) {
+            return ResponseEntity.status(HttpStatus.BAD_REQUEST)
+                    .body(ApiResponse.build(HttpStatus.BAD_REQUEST, "Only one of username or email must be provided", null));
+        }
+        boolean isAvailable;
+        String field;
+        if (username != null) {
+            isAvailable = validationUtils.isUsernameAvailable(username);
+            field = "username";
+        } else {
+            isAvailable = validationUtils.isEmailAvailable(email);
+            field = "email";
+        }
+        String message = isAvailable ? field + " is available" : field + " is already taken";
+        return ResponseEntity.ok(ApiResponse.build(HttpStatus.OK, message, isAvailable));
+    }
+
+    @Operation(summary = "Get validity of recovery code for a given email")
+    @PostMapping("/recovery-code")
+    public ResponseEntity<?> checkRecoveryCodeValidity(@RequestParam String rawCode, @RequestParam String email,
+                                                       HttpServletRequest req) {
+
+        Optional<Bucket> bucketOpt = rateLimitUtils
+                .getBucketByUserOrIp(userService.getCurrentUser(), RateLimitUtils.extractClientIp(req));
+        if (bucketOpt.isEmpty() || !bucketOpt.get().tryConsume(1)) {
+            return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
+                    .body(ApiResponse.build(HttpStatus.TOO_MANY_REQUESTS, "Too many requests - rate limit exceeded", null));
+        }
+
+        boolean isValid = userTokenService.isRecoveryCodeValid(rawCode, email);
+        String message = isValid ? "Recovery code is valid" : "Invalid recovery code or email";
+        return ResponseEntity.ok(ApiResponse.build(HttpStatus.OK, message, isValid));
+    }
+
+    @Operation(summary = "Health check endpoint")
+    @GetMapping("/health")
+    @ResponseBody
+    public ResponseEntity<?> health() {
+        return ResponseEntity.ok(Map.of("status", "ok"));
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/converter/JsonNodeConverter.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/converter/JsonNodeConverter.java
@@ -0,0 +1,29 @@
+package dev.ivfrost.hydro_backend.converter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+@Converter
+public class JsonNodeConverter implements AttributeConverter<JsonNode, String> {
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Override
+    public String convertToDatabaseColumn(JsonNode attribute) {
+        try {
+            return objectMapper.writeValueAsString(attribute);
+        } catch (Exception e) {
+            throw new IllegalArgumentException("Error converting JsonNode to String", e);
+        }
+    }
+
+    @Override
+    public JsonNode convertToEntityAttribute(String dbData) {
+        try {
+            return objectMapper.readTree(dbData);
+        } catch (Exception e) {
+            throw new IllegalArgumentException("Error converting String to JsonNode", e);
+        }
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/ApiResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/ApiResponse.java
@@ -0,0 +1,19 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import org.springframework.http.HttpStatus;
+
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+public class ApiResponse<T> {
+    private int status;
+    private String message;
+    private T data;
+
+    public static <T> ApiResponse<T> build(HttpStatus status, String message, T data) {
+        return new ApiResponse<>(status.value(), message, data);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/AuthResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/AuthResponse.java
@@ -0,0 +1,12 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+@Getter
+@AllArgsConstructor
+public class AuthResponse {
+    private final String token;
+    private final String refreshToken;
+    private final String message;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceLinkRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceLinkRequest.java
@@ -0,0 +1,15 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import jakarta.persistence.Column;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DeviceLinkRequest {
+
+    @Column(length = 44, nullable = false)
+    private String hash;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceProvisionRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceProvisionRequest.java
@@ -0,0 +1,21 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DeviceProvisionRequest {
+
+    @Size(max = 20, min = 4)
+    private String firmware;
+
+    @Size(max = 40, min = 4)
+    private String technicalName;
+
+    @Size(max = 100, min = 4)
+    private String macAddress;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceResponse.java
@@ -0,0 +1,28 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.Instant;
+
+@NoArgsConstructor
+@AllArgsConstructor
+@Data
+public class DeviceResponse {
+    private Long id;
+    private String name;
+    private String location;
+    private String firmware;
+    private String technicalName;
+    private String ip;
+    private Instant createdAt;
+    private Instant updatedAt;
+    private Instant linkedAt;
+    private Instant lastSeen;
+    private User user;
+    private Integer displayOrder;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceUpdateRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/DeviceUpdateRequest.java
@@ -0,0 +1,14 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DeviceUpdateRequest {
+
+    private String name;
+    private Integer displayOrder;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/MqttCredentialsResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/MqttCredentialsResponse.java
@@ -0,0 +1,13 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class MqttCredentialsResponse {
+    public String username;
+    public String password;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/PasswordResetRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/PasswordResetRequest.java
@@ -0,0 +1,20 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+@Data
+@AllArgsConstructor
+public class PasswordResetRequest {
+
+    @Email(message = "Invalid email format")
+    private final String email;
+
+    @Size(min = 11, max = 11, message = "Recovery code must be exactly 11 characters long")
+    private final String recoveryCode;
+
+    @Size(min = 8, max = 60, message = "Password must be between 8 and 60 characters long")
+    private final String newPassword;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/ResetPasswordRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/ResetPasswordRequest.java
@@ -0,0 +1,24 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+@Data
+@AllArgsConstructor
+public class ResetPasswordRequest {
+
+    @NotBlank
+    @Email
+    String email;
+
+    @NotBlank
+    @Size(min = 16, max = 16)
+    String recoveryCode;
+
+    @NotBlank
+    @Size(min = 8, max = 60)
+    String newPassword;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/UserLoginRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/UserLoginRequest.java
@@ -0,0 +1,22 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.persistence.Column;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class UserLoginRequest {
+
+    @Email
+    @Size(min = 5, max = 60)
+    private String email;
+
+    @Size(min = 8, max = 60)
+    private String password;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/UserRegisterRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/UserRegisterRequest.java
@@ -0,0 +1,34 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class UserRegisterRequest {
+
+    @NotBlank
+    @Email
+    @Size(min = 5, max = 60)
+    private String email;
+
+    @NotBlank
+    @Size(min = 5, max = 20)
+    private String username;
+
+    @NotBlank
+    @Size(min = 6, max = 40)
+    private String fullName;
+
+    @NotBlank
+    @Size(min = 8, max = 60)
+    private String password;
+
+    @Size(min = 2, max = 2)
+    private String preferredLanguage;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/UserRegisterResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/UserRegisterResponse.java
@@ -0,0 +1,11 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+@AllArgsConstructor
+@Data
+public class UserRegisterResponse {
+
+    String[] recoveryCodes;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/UserResponse.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/UserResponse.java
@@ -0,0 +1,44 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import dev.ivfrost.hydro_backend.entity.User;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.Instant;
+import java.util.List;
+
+@NoArgsConstructor
+@AllArgsConstructor
+@Data
+public class UserResponse {
+
+    private Long id;
+
+    private String username;
+
+    private String fullName;
+
+    private String email;
+
+    private String profilePictureUrl;
+
+    private String phoneNumber;
+
+    private String address;
+
+    private Instant createdAt;
+
+    private Instant updatedAt;
+
+    private Instant lastLogin;
+
+    private User.Role role;
+
+    private String preferredLanguage;
+
+    private JsonNode settings;
+
+    private List<DeviceResponse> devices;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/dto/UserUpdateRequest.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/dto/UserUpdateRequest.java
@@ -0,0 +1,39 @@
+package dev.ivfrost.hydro_backend.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+
+@Data
+@AllArgsConstructor
+public class UserUpdateRequest {
+    @Size(min = 5, max = 20)
+    private String username;
+
+    @Size(min = 4, max = 40)
+    private String fullName;
+
+    @Email(message = "Invalid email format")
+    @Size(min = 8, max = 50)
+    private String email;
+
+    @Size(max = 255)
+    private String profilePictureUrl;
+
+    @Pattern(regexp = "^\\+?[0-9\\-\\s]{7,20}$", message = "Invalid phone number format")
+    @Size(max = 20)
+    private String phoneNumber;
+
+    @Size(max = 100)
+    private String address;
+
+    @Size(min = 2, max = 2)
+    private String preferredLanguage = "es";
+
+    private JsonNode settings = new ObjectMapper().createObjectNode();
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/entity/Device.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/entity/Device.java
@@ -0,0 +1,77 @@
+package dev.ivfrost.hydro_backend.entity;
+
+import jakarta.persistence.*;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import java.time.Instant;
+
+// Non-nullable: firmware, technicalName
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "devices")
+@Entity
+public class Device {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Size(max = 17, min = 17)
+    @Column(nullable = false, name = "mac_address", unique = true)
+    private String macAddress;
+
+    @Size(min = 1, max = 40)
+    @Column(nullable = true)
+    private String name; // User defined name
+
+    @Size(max = 20)
+    @Column(length = 20)
+    private String location; // Latest known location
+
+    @Size(max = 20)
+    @Column(nullable = false)
+    private String firmware; // Firmware version
+
+    @Size(max = 40)
+    @Column(name = "technical_name", nullable = false)
+    private String technicalName; // Technical name
+
+    @Column(length = 44, unique = true)
+    private String hash; // Unique device hash for verification
+
+    @Pattern(regexp = "^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$")
+    @Size(max = 15)
+    @Column(nullable = true)
+    private String ip;
+
+    @Column(name = "created_at")
+    private Instant createdAt; // Timestamp when the device was created
+
+    @UpdateTimestamp
+    @Column(name = "updated_at")
+    private Instant updatedAt;
+
+    private Instant linkedAt;
+
+    private Instant lastSeen;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id")
+    private User user;
+
+    @Column(name = "display_order")
+    private Integer displayOrder; // User-defined order for display purposes
+
+    @PrePersist
+    protected void onCreate() {
+        Instant now = Instant.now();
+        this.createdAt = now;
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/entity/MqttCredentials.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/entity/MqttCredentials.java
@@ -0,0 +1,29 @@
+package dev.ivfrost.hydro_backend.entity;
+
+import jakarta.persistence.*;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@NoArgsConstructor
+@AllArgsConstructor
+@Data
+@Entity
+public class MqttCredentials {
+
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Id
+    private Long id;
+
+    @Size(min = 5, max = 20)
+    @Column(nullable = false, unique = true)
+    private String username;
+
+    @Column(length = 44, nullable = false)
+    private String password;
+
+    @OneToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id", nullable = false)
+    private User user;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/entity/User.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/entity/User.java
@@ -0,0 +1,127 @@
+package dev.ivfrost.hydro_backend.entity;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.ivfrost.hydro_backend.converter.JsonNodeConverter;
+import jakarta.persistence.*;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+import lombok.AllArgsConstructor;
+import lombok.NoArgsConstructor;
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.annotations.UpdateTimestamp;
+import org.hibernate.type.SqlTypes;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "users")
+@Entity
+public class User {
+
+    public static enum Role {
+        USER,
+        ADMIN
+    }
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Size(min = 5, max = 20)
+    @Column(unique = true, nullable = false)
+    private String username;
+
+    // Password is write-only to prevent it from being serialized in responses
+    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
+    @Size(min = 12, max = 60)
+    @Column(nullable = false)
+    private String password;
+
+    @Size(min = 4, max = 40)
+    @Column(name = "full_name", nullable = false)
+    private String fullName;
+
+    @Email(message = "Invalid email format")
+    @Size(min = 8, max = 50)
+    @Column(unique = true, nullable = false)
+    private String email;
+
+    @Column(name = "profile_pic")
+    @Size(max = 255)
+    private String profilePictureUrl;
+
+    @Size(max = 20)
+    @Column(name = "phone_number")
+    private String phoneNumber;
+
+    @Size(max = 100)
+    @Column(columnDefinition = "text")
+    private String address;
+
+    @CreationTimestamp
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private Instant createdAt;
+
+    @UpdateTimestamp
+    @Column(name = "updated_at", nullable = false)
+    private Instant updatedAt;
+
+    @Column(name = "deleted_at", nullable = true)
+    private Instant deletedAt;
+
+    @Column(name = "last_login")
+    private Instant lastLogin;
+
+    @Column(name = "is_active", nullable = false)
+    private boolean isActive = true;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private Role role = Role.USER;
+
+    @Size(min = 2, max = 2)
+    @Column(name = "preferred_language", nullable = false)
+    private String preferredLanguage = "es";
+
+    @Convert(converter = JsonNodeConverter.class)
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "settings", columnDefinition = "jsonb")
+    private JsonNode settings = new ObjectMapper().createObjectNode();
+
+    @Column(columnDefinition = "text")
+    private String notes;
+
+    @OneToMany(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id")
+    private List<Device> devices = new ArrayList<>();
+
+    @Column(name = "is_deleted", nullable = false)
+    private boolean isDeleted = false;
+
+    // Enforce preferredLanguage to be a 2-letter ISO code in lowercase
+    public void setPreferredLanguage(String preferredLanguage) {
+        if (preferredLanguage == null || preferredLanguage.length() != 2) {
+            throw new IllegalArgumentException("Preferred language must be a 2-letter ISO code.");
+        }
+        this.preferredLanguage = preferredLanguage.toLowerCase();
+    }
+
+    @PrePersist
+    protected void onCreate() {
+        if (profilePictureUrl == null) profilePictureUrl = "";
+        if (phoneNumber == null) phoneNumber = "";
+        if (address == null) address = "";
+        if (lastLogin == null) lastLogin = Instant.now();
+        if (settings == null) settings = new ObjectMapper().createObjectNode();
+        if (notes == null) notes = "";
+        if (devices == null) devices = new ArrayList<>();
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/entity/UserToken.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/entity/UserToken.java
@@ -0,0 +1,34 @@
+package dev.ivfrost.hydro_backend.entity;
+
+import jakarta.persistence.*;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@Entity
+@Table(name = "tokens")
+public class UserToken {
+
+    public static enum TokenType {
+        RECOVERY_CODE,
+    }
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, length = 44)
+    private String token;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 20)
+    private TokenType type;
+
+    @Column(name = "expiry_date", nullable = true)
+    private LocalDateTime expiryDate;
+
+    @ManyToOne
+    @JoinColumn(name = "user_id", nullable = false)
+    private User user;
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/AuthWrongPasswordException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/AuthWrongPasswordException.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class AuthWrongPasswordException extends RuntimeException {
+    public AuthWrongPasswordException(String email) {
+        super("Wrong password for user with email: " + email);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceFetchException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceFetchException.java
@@ -0,0 +1,8 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class DeviceFetchException extends RuntimeException {
+
+    public DeviceFetchException(String message) {
+        super(message);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceLinkException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceLinkException.java
@@ -0,0 +1,8 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class DeviceLinkException extends RuntimeException {
+
+    public DeviceLinkException(String hash) {
+        super("Device with hash " + hash + " is already linked to a user.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceNotFoundException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/DeviceNotFoundException.java
@@ -0,0 +1,11 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class DeviceNotFoundException extends RuntimeException {
+    public DeviceNotFoundException(Long deviceId) {
+        super("Device with ID " + deviceId + " not found.");
+    }
+
+    public DeviceNotFoundException(String hash) {
+        super("Device with hash " + hash + " not found.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/ExpiredVerificationToken.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/ExpiredVerificationToken.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class ExpiredVerificationToken extends RuntimeException {
+    public ExpiredVerificationToken(String message) {
+        super(message);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/RecoveryTokenMismatchException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/RecoveryTokenMismatchException.java
@@ -0,0 +1,8 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class RecoveryTokenMismatchException extends RuntimeException {
+    public RecoveryTokenMismatchException(String message) {
+        super(message);
+    }
+}
+
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/RecoveryTokenNotFoundException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/RecoveryTokenNotFoundException.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class RecoveryTokenNotFoundException extends RuntimeException {
+    public RecoveryTokenNotFoundException(String message) {
+        super(message);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/TokenNotFoundException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/TokenNotFoundException.java
@@ -0,0 +1,9 @@
+package dev.ivfrost.hydro_backend.exception;
+
+import dev.ivfrost.hydro_backend.entity.UserToken;
+
+public class TokenNotFoundException extends RuntimeException {
+    public TokenNotFoundException(UserToken.TokenType type) {
+        super("Token of type " + type + " not found or invalid.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/UserDeletedException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/UserDeletedException.java
@@ -0,0 +1,8 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class UserDeletedException extends RuntimeException {
+
+    public UserDeletedException(Long userId) {
+        super("User with ID " + userId + " is deleted.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/UserNotAuthenticatedException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/UserNotAuthenticatedException.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class UserNotAuthenticatedException extends Exception {
+    public UserNotAuthenticatedException(String message) {
+        super(message);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/UserNotFoundException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/UserNotFoundException.java
@@ -0,0 +1,13 @@
+package dev.ivfrost.hydro_backend.exception;
+
+import jakarta.validation.constraints.Size;
+
+public class UserNotFoundException extends RuntimeException {
+    public UserNotFoundException(Long userId) {
+        super("User with ID " + userId + " not found.");
+    }
+
+    public UserNotFoundException(String email) {
+        super("User with email '" + email + "' not found.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/exception/UsernameTakenException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/exception/UsernameTakenException.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.exception;
+
+public class UsernameTakenException extends RuntimeException {
+    public UsernameTakenException(String username) {
+        super("Username '" + username + "' is already taken.");
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/repository/DeviceRepository.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/repository/DeviceRepository.java
@@ -0,0 +1,13 @@
+package dev.ivfrost.hydro_backend.repository;
+
+import dev.ivfrost.hydro_backend.entity.Device;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface DeviceRepository extends JpaRepository<Device, Long> {
+    Optional<Device> findByHash(String hash);
+
+    List<Device> findAllByUserId(Long userId);
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/repository/MqttCredentialsRepository.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/repository/MqttCredentialsRepository.java
@@ -0,0 +1,12 @@
+package dev.ivfrost.hydro_backend.repository;
+
+import dev.ivfrost.hydro_backend.entity.MqttCredentials;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.Optional;
+
+public interface MqttCredentialsRepository extends JpaRepository<MqttCredentials, Long> {
+
+    boolean existsByUserId(Long userId);
+    Optional<MqttCredentials> findByUserId(Long userId);
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/repository/UserRepository.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/repository/UserRepository.java
@@ -0,0 +1,21 @@
+package dev.ivfrost.hydro_backend.repository;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Size;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+
+import java.util.Optional;
+
+public interface UserRepository extends JpaRepository<User, Long> {
+    Optional<User> findByUsername(String username);
+    Optional<User> findByEmail(String email);
+
+    @Query("SELECT u FROM User u LEFT JOIN FETCH u.devices WHERE u.id = :id")
+    Optional<User> findByIdWithDevices(Long id);
+
+    boolean existsByUsername(String username);
+    boolean existsByEmail(String email);
+
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/repository/UserTokenRepository.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/repository/UserTokenRepository.java
@@ -0,0 +1,10 @@
+package dev.ivfrost.hydro_backend.repository;
+
+import dev.ivfrost.hydro_backend.entity.UserToken;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.Optional;
+
+public interface UserTokenRepository extends JpaRepository<UserToken, Long> {
+    Optional<UserToken> findByTokenAndType(String token, UserToken.TokenType type);
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/security/JWTFilter.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/security/JWTFilter.java
@@ -0,0 +1,100 @@
+package dev.ivfrost.hydro_backend.security;
+
+import com.auth0.jwt.exceptions.JWTVerificationException;
+import com.auth0.jwt.interfaces.Claim;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.AllArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.IOException;
+import java.util.Map;
+
+@Slf4j
+@AllArgsConstructor
+@Component
+public class JWTFilter extends OncePerRequestFilter {
+
+    private final UserDetailsService userDetailsService;
+    private final JWTUtil jwtUtil;
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
+            throws ServletException, IOException {
+        String path = request.getRequestURI();
+        log.info("JWTFilter processing path: {}", path);
+
+        // Bypass filter for authentication and validation endpoints
+        if (path.startsWith("/v1/users/auth/") || path.equals("/v1/users") ||
+            path.equals("/v1/users/recover") || path.equals("/v1/users/password/reset") ||
+            path.startsWith("/v1/validation") || path.startsWith("/v1/users/verify") ||
+            path.equals("/v1/validation/recovery-code")) {
+
+            log.info("Bypassing JWTFilter for path: {}", path);
+            filterChain.doFilter(request, response);
+            return;
+        }
+
+        // Extract Authorization header
+        String authHeader = request.getHeader("Authorization");
+        log.info("Authorization header: {}", authHeader);
+        // Check for Bearer token
+        if (authHeader != null && !authHeader.isBlank() && authHeader.startsWith("Bearer ")) {
+            // Extract JWT token
+            String jwt = authHeader.substring(7);
+            log.info("Extracted JWT: {}", jwt);
+            if (jwt == null || jwt.isBlank()) {
+                log.warn("JWT is blank or null");
+                response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Invalid JWT Token in Bearer Header");
+                return;
+            }
+            try {
+                // Validate token and retrieve claims
+                Map<String, Claim> claims = jwtUtil.validateTokenAndRetrieveClaims(jwt);
+                log.info("JWT claims: {}", claims);
+                String username = claims.get("username").asString();
+                String role = claims.get("role") != null ? claims.get("role").asString() : null;
+                log.info("JWT username: {}, role: {}", username, role);
+
+                // Load User Details
+                UserDetails userDetails = userDetailsService.loadUserByUsername(username);
+                log.info("Loaded userDetails: {}", userDetails);
+                log.info("User authorities: {}", userDetails.getAuthorities());
+
+                // Use authorities from userDetails (database), not JWT
+                UsernamePasswordAuthenticationToken authToken =
+                        new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities());
+
+                // Set authentication in security context
+                if (SecurityContextHolder.getContext().getAuthentication() == null) {
+                    SecurityContextHolder.getContext().setAuthentication(authToken);
+                    log.info("Authentication set in security context for user: {}", username);
+                } else {
+                    log.info("Authentication already present in security context");
+                }
+            } catch (JWTVerificationException e) {
+                log.error("JWT verification failed", e);
+                response.sendError(HttpServletResponse.SC_BAD_REQUEST, "Invalid JWT Token in Bearer Header");
+            } catch (Exception e) {
+                log.error("Unexpected error in JWTFilter", e);
+                response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Authentication failed");
+            }
+        } else {
+            log.info("No Bearer token found in Authorization header");
+        }
+
+        // Continue filter chain
+        filterChain.doFilter(request, response);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/security/JWTUtil.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/security/JWTUtil.java
@@ -0,0 +1,65 @@
+package dev.ivfrost.hydro_backend.security;
+
+import com.auth0.jwt.JWT;
+import com.auth0.jwt.algorithms.Algorithm;
+import com.auth0.jwt.exceptions.JWTCreationException;
+import com.auth0.jwt.exceptions.JWTVerificationException;
+import com.auth0.jwt.interfaces.Claim;
+import com.auth0.jwt.interfaces.DecodedJWT;
+import dev.ivfrost.hydro_backend.entity.User;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.util.Date;
+import java.util.Map;
+
+@Component
+public class JWTUtil {
+
+    // Inject JWT secret from application properties
+    @Value("${jwt.secret}")
+    private String jwtSecret;
+    @Value("${jwt.expiration-ms}")
+    private Long jwtExpirationMs;
+    @Value("${jwt.refresh-expiration-ms}")
+    private Long jwtRefreshExpirationMs;
+
+    // Create JWT token using the injected secret
+    public String generateToken(User user) throws JWTCreationException {
+        return JWT.create()
+                .withSubject("User Details")
+                .withClaim("username", user.getUsername())
+                .withClaim("email", user.getEmail())
+                .withClaim("role", user.getRole().toString())
+                .withClaim("preferredLanguage", user.getPreferredLanguage())
+                .withExpiresAt(new Date(System.currentTimeMillis() + jwtExpirationMs))
+                .withIssuedAt(new Date())
+                .withIssuer("HydroBackend")
+                .sign(Algorithm.HMAC256(jwtSecret));
+    }
+
+    // Create JWT refresh token using the injected secret and longer expiration
+    public String generateRefreshToken(User user) throws JWTCreationException {
+        return JWT.create()
+                .withSubject("User Details")
+                .withClaim("username", user.getUsername())
+                .withClaim("email", user.getEmail())
+                .withClaim("role", user.getRole().toString())
+                .withClaim("preferredLanguage", user.getPreferredLanguage())
+                .withExpiresAt(new Date(System.currentTimeMillis() + jwtRefreshExpirationMs))
+                .withIssuedAt(new Date())
+                .withIssuer("HydroBackend")
+                .sign(Algorithm.HMAC256(jwtSecret));
+    }
+
+    public Map<String, Claim> validateTokenAndRetrieveClaims(String token) throws JWTVerificationException {
+        DecodedJWT jwt = JWT.require(Algorithm.HMAC256(jwtSecret))
+                .withSubject("User Details")
+                .withIssuer("HydroBackend")
+                .build()
+                .verify(token);
+
+        return jwt.getClaims();
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/security/MyUserDetails.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/security/MyUserDetails.java
@@ -0,0 +1,52 @@
+package dev.ivfrost.hydro_backend.security;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import lombok.AllArgsConstructor;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.userdetails.UserDetails;
+
+import java.util.Collection;
+import java.util.Collections;
+
+@AllArgsConstructor
+public class MyUserDetails implements UserDetails {
+
+    private final User user;
+
+    @Override
+    public Collection<? extends GrantedAuthority> getAuthorities() {
+        return Collections.singletonList(
+                new SimpleGrantedAuthority("ROLE_" + user.getRole().name()));
+    }
+
+    @Override
+    public String getPassword() {
+        return user.getPassword();
+    }
+
+    @Override
+    public String getUsername() {
+        return String.valueOf(user.getId());
+    }
+
+    @Override
+    public boolean isEnabled() {
+        return !user.isDeleted() && user.isActive();
+    }
+
+    @Override
+    public boolean isAccountNonExpired() {
+        return true;
+    }
+
+    @Override
+    public boolean isAccountNonLocked() {
+        return true;
+    }
+
+    @Override
+    public boolean isCredentialsNonExpired() {
+        return true;
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/DeviceService.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/DeviceService.java
@@ -0,0 +1,326 @@
+// language: java
+package dev.ivfrost.hydro_backend.service;
+
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.entity.Device;
+import dev.ivfrost.hydro_backend.entity.MqttCredentials;
+import dev.ivfrost.hydro_backend.entity.User;
+import dev.ivfrost.hydro_backend.exception.DeviceFetchException;
+import dev.ivfrost.hydro_backend.exception.DeviceLinkException;
+import dev.ivfrost.hydro_backend.exception.DeviceNotFoundException;
+import dev.ivfrost.hydro_backend.repository.DeviceRepository;
+import dev.ivfrost.hydro_backend.repository.MqttCredentialsRepository;
+import dev.ivfrost.hydro_backend.util.DeviceDtoUtil;
+import jakarta.transaction.Transactional;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+@Service
+public class DeviceService {
+    private final DeviceRepository deviceRepository;
+    private final MqttCredentialsRepository mqttCredentialsRepository;
+    private final EncoderService encoderService;
+    private final String privateKey;
+    private final UserService userService;
+
+    public DeviceService(
+            DeviceRepository deviceRepository,
+            MqttCredentialsRepository mqttCredentialsRepository,
+            EncoderService encoderService,
+            @Value("${device.secret}") String privateKey,
+            UserService userService) {
+
+        this.deviceRepository = deviceRepository;
+        this.mqttCredentialsRepository = mqttCredentialsRepository;
+        this.encoderService = encoderService;
+        this.privateKey = privateKey;
+        if (this.privateKey == null || this.privateKey.isEmpty()) {
+            throw new IllegalStateException("Environment variable DEVICE_SECRET is not set.");
+        }
+        this.userService = userService;
+    }
+
+    /**
+     * Provisions a new device and generates an ownership hash using the database ID.
+     *
+     * @param req the device provision request DTO
+     * @return the provisioned device response DTO
+     */
+    @Transactional
+    public DeviceResponse provisionDevice(DeviceProvisionRequest req) {
+        Device device = convertRequestToDevice(req);
+
+        // Persist to get generated ID
+        Device savedDevice = deviceRepository.save(device);
+
+        // Compute and set hash based on generated ID
+        String hash = encoderService.hmacSha256Encoder().apply(privateKey, savedDevice.getId().toString());
+        savedDevice.setHash(hash);
+
+        // Persist updated record with hash
+        return DeviceDtoUtil.convertDeviceToResponse(deviceRepository.save(savedDevice));
+    }
+
+    /**
+     * Links an unlinked device to a user; creates MQTT credentials if user's first device; sets device order.
+     *
+     * @param req    the device link request DTO
+     * @param userId the ID of the user to link the device to (null for authenticated user)
+     * @throws DeviceLinkException     if the device is already linked
+     * @throws DeviceNotFoundException if the device is not found
+     */
+    @Transactional
+    public void linkDevice(DeviceLinkRequest req, Long userId) {
+        // Determine the user (either from provided ID or current authentication context)
+        User user = (userId != null)
+                ? userService.getUserByIdWithoutDevices(userId)
+                : userService.getCurrentUserWithoutDevices();
+
+        // Find the device by hash
+        Device device = deviceRepository.findByHash(req.getHash())
+                .orElseThrow(() -> new DeviceNotFoundException(req.getHash()));
+
+        // Check if device is already linked
+        if (device.getUser() != null) {
+            throw new DeviceLinkException(req.getHash());
+        }
+
+        ensureMqttCredentialsForUser(user);
+
+        // Link device to user
+        device.setUser(user);
+        // Set device order to be the highest order + 1 for initial display at the bottom of the list
+        device.setDisplayOrder(calculateDeviceDisplayOrder(user));
+        deviceRepository.save(device);
+    }
+
+    /**
+     * Overloaded method for device linking requests coming from authenticated users.
+     *
+     * @param req the device link request DTO
+     * @throws DeviceLinkException     if the device is already linked
+     * @throws DeviceNotFoundException if the device is not found
+     */
+    @Transactional
+    public void linkDevice(DeviceLinkRequest req) {
+        linkDevice(req, null);
+    }
+
+    /**
+     * Unlinks a device from the currently authenticated user.
+     *
+     * @param deviceId the ID of the device to unlink
+     * @throws DeviceNotFoundException  if the device is not found
+     * @throws IllegalArgumentException if the device does not belong to the authenticated user
+     */
+    @Transactional
+    public void unlinkDevice(Long deviceId) {
+        Device device = deviceRepository.findById(deviceId)
+                .orElseThrow(() -> new DeviceNotFoundException(deviceId));
+        User currentUser = userService.getCurrentUserWithoutDevices();
+        if (!Objects.equals(device.getUser(), currentUser)) {
+            throw new IllegalArgumentException("Device does not belong to the authenticated user");
+        }
+        device.setUser(null);
+        deviceRepository.save(device);
+    }
+
+    /**
+     * Retrieves existing MQTT credentials for the currently authenticated user.
+     * The password is returned as stored in the database (hash generated from user ID and private key).
+     *
+     * @return the MQTT credentials response DTO
+     * @throws IllegalArgumentException if credentials are not found for the user
+     */
+    public MqttCredentialsResponse getMqttCredentials() {
+        User user = userService.getCurrentUserWithoutDevices();
+        MqttCredentials mqttCredentials = mqttCredentialsRepository.findByUserId(user.getId())
+                .orElseThrow(() -> new IllegalArgumentException("MQTT credentials not found for user"));
+        // Return the password as stored in the database
+        return new MqttCredentialsResponse(mqttCredentials.getUsername(), mqttCredentials.getPassword());
+    }
+
+    /**
+     * Retrieves devices owned by the currently authenticated user.
+     *
+     * @return a list of device response DTOs
+     * @throws DeviceFetchException if no devices are found for the user
+     */
+    public List<DeviceResponse> getUserDevices() {
+        User user = userService.getCurrentUser();
+
+        if (user.getDevices() == null || user.getDevices().isEmpty()) {
+            throw new DeviceFetchException("No devices found for user");
+        }
+
+        return user.getDevices()
+                .stream()
+                .map(DeviceDtoUtil::convertDeviceToResponse)
+                .sorted(Comparator.comparing(DeviceResponse::getDisplayOrder))
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Retrieves devices owned by a specific user, by user ID (Admin only).
+     *
+     * @param userId the ID of the user whose devices are to be retrieved
+     * @return a list of device response DTOs
+     * @throws DeviceFetchException if no devices are found for the user
+     */
+    public List<DeviceResponse> getUserDevicesById(Long userId) {
+        User user = userService.getUserById(userId);
+        if (user.getDevices() == null || user.getDevices().isEmpty()) {
+            throw new DeviceFetchException("No devices found for user");
+        }
+        return user
+                .getDevices()
+                .stream()
+                .map(DeviceDtoUtil::convertDeviceToResponse)
+                .sorted(Comparator.comparing(DeviceResponse::getDisplayOrder))
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Retrieves all devices provisioned in the system (Admin only).
+     *
+     * @return a list of all device response DTOs
+     * @throws DeviceFetchException if no devices are found
+     */
+    public List<DeviceResponse> getAllDevices() {
+        List<Device> devices = deviceRepository.findAll();
+        if (devices.isEmpty()) {
+            throw new DeviceFetchException("No devices found");
+        }
+        return DeviceDtoUtil.convertDevicesToResponse(devices);
+    }
+
+    /**
+     * Updates fields of a specific device by its ID.
+     * Admins can additionally update the technical name and firmware version.
+     *
+     * @param deviceId      the ID of the device to update
+     * @param req           the device update request DTO
+     * @param technicalName (Admin only) the new technical name for the device
+     * @param firmware      (Admin only) the new firmware version for the device
+     * @return the updated device response DTO
+     * @throws DeviceNotFoundException  if the device is not found
+     * @throws IllegalArgumentException if the device does not belong to the authenticated user
+     */
+    public DeviceResponse updateDeviceById(
+            Long deviceId, DeviceUpdateRequest req, String technicalName, String firmware) {
+
+        Device device = deviceRepository.findById(deviceId)
+                .orElseThrow(() -> new DeviceNotFoundException(deviceId));
+
+        // If either technicalName or firmware is null, it's a user request; verify ownership
+        if (technicalName == null || firmware == null) {
+            User currentUser = userService.getCurrentUserWithoutDevices();
+            if (!Objects.equals(device.getUser(), currentUser)) {
+                throw new IllegalArgumentException("Device does not belong to the authenticated user");
+            }
+        }
+
+        if (technicalName != null && !technicalName.isEmpty()) {
+            device.setTechnicalName(technicalName);
+        }
+        if (firmware != null && !firmware.isEmpty()) {
+            device.setFirmware(firmware);
+        }
+        if (req.getName() != null && !req.getName().isEmpty()) {
+            device.setName(req.getName());
+        }
+        if (req.getDisplayOrder() != null && req.getDisplayOrder() >= 0) {
+            device.setDisplayOrder(req.getDisplayOrder());
+        }
+
+        return DeviceDtoUtil.convertDeviceToResponse(deviceRepository.save(device));
+    }
+
+    /**
+     * Overloaded method for updating a device by its ID for authenticated users.
+     * Users can only update the user-defined name and display order of their own devices.
+     *
+     * @param deviceId the ID of the device to update
+     * @param req      the device update request DTO
+     * @return the updated device response DTO
+     */
+    public DeviceResponse updateUserDeviceById(Long deviceId, DeviceUpdateRequest req) {
+        return updateDeviceById(deviceId, req, null, null);
+    }
+
+    /**
+     * Delete a device by its ID (Admin only).
+     *
+     * @param deviceId the ID of the device to delete
+     * @throws DeviceNotFoundException if the device is not found
+     */
+    public void deleteDeviceById(Long deviceId) {
+        Device device = deviceRepository.findById(deviceId).orElseThrow(() -> new DeviceNotFoundException(deviceId));
+        deviceRepository.delete(device);
+    }
+
+    /*--------------------------*/
+    /*      Helper Methods      */
+    /*--------------------------*/
+
+    /**
+     * Converts a DeviceProvisionRequest DTO to a Device entity.
+     *
+     * @param req the device provision request DTO
+     * @return the device entity
+     */
+    private Device convertRequestToDevice(DeviceProvisionRequest req) {
+        Device device = new Device();
+        device.setTechnicalName(req.getTechnicalName());
+        device.setFirmware(req.getFirmware());
+        device.setMacAddress(req.getMacAddress());
+        return device;
+    }
+
+    /**
+     * Converts MqttCredentials entity to MqttCredentialsResponse DTO.
+     *
+     * @param mqttCredentials the MQTT credentials entity
+     * @return the MQTT credentials response DTO
+     */
+    private MqttCredentialsResponse convertMqttCredentialsToResponse(MqttCredentials mqttCredentials) {
+        return new MqttCredentialsResponse(mqttCredentials.getUsername(), mqttCredentials.getPassword());
+    }
+
+    /**
+     * Ensures MQTT credentials exist for the user, creating them if not present.
+     *
+     * @param user the user to check/create credentials for
+     */
+    private void ensureMqttCredentialsForUser(User user) {
+        if (!mqttCredentialsRepository.existsByUserId(user.getId())) {
+            String encodedPassword = encoderService.hmacSha256Encoder().apply(privateKey, user.getId().toString());
+            MqttCredentials mqttCredentials = new MqttCredentials();
+            mqttCredentials.setUsername(user.getUsername());
+            mqttCredentials.setPassword(encodedPassword);
+            mqttCredentials.setUser(user);
+            mqttCredentialsRepository.save(mqttCredentials);
+        }
+    }
+
+    /**
+     * Calculates the next display order for a user's devices.
+     *
+     * @param user the user whose devices are being ordered
+     * @return the next display order
+     */
+    private int calculateDeviceDisplayOrder(User user) {
+        return user.getDevices() != null && !user.getDevices().isEmpty()
+                ? user.getDevices().stream()
+                .mapToInt(Device::getDisplayOrder)
+                .max()
+                .orElse(0) + 1
+                : 1;
+    }
+
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/EncoderService.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/EncoderService.java
@@ -0,0 +1,29 @@
+package dev.ivfrost.hydro_backend.service;
+
+import org.springframework.stereotype.Service;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.util.Base64;
+import java.util.function.BiFunction;
+
+@Service
+public class EncoderService {
+
+    public BiFunction<String, String, String> hmacSha256Encoder() {
+        return (secretKey, toBeEncoded) -> {
+            try {
+                if (toBeEncoded == null || toBeEncoded.isEmpty()) {
+                    throw new IllegalArgumentException("Input string to be encoded cannot be null or empty");
+                }
+                Mac mac = Mac.getInstance("HmacSHA256");
+                SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
+                mac.init(secretKeySpec);
+                byte[] hmac = mac.doFinal(toBeEncoded.getBytes());
+                return Base64.getEncoder().encodeToString(hmac);
+            } catch (Exception e) {
+                throw new HmacEncodingException("Error while encoding string using HMAC-SHA256");
+            }
+        };
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/HmacEncodingException.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/HmacEncodingException.java
@@ -0,0 +1,7 @@
+package dev.ivfrost.hydro_backend.service;
+
+public class HmacEncodingException extends RuntimeException {
+    public HmacEncodingException(String s) {
+        super(s);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/MyUserDetailsService.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/MyUserDetailsService.java
@@ -0,0 +1,31 @@
+package dev.ivfrost.hydro_backend.service;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import dev.ivfrost.hydro_backend.repository.UserRepository;
+import dev.ivfrost.hydro_backend.security.MyUserDetails;
+import lombok.AllArgsConstructor;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+import org.springframework.stereotype.Service;
+
+import java.util.Optional;
+
+@AllArgsConstructor
+@Service
+public class MyUserDetailsService implements UserDetailsService {
+
+    private final UserRepository userRepository;
+
+    @Override
+    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
+        Optional<User> userOpt = userRepository.findByUsername(username);
+        if (userOpt.isEmpty()) {
+            throw new UsernameNotFoundException("User not found: " + username);
+        }
+        User user = userOpt.get();
+        return new MyUserDetails(user);
+    }
+
+
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/UserService.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/UserService.java
@@ -0,0 +1,394 @@
+package dev.ivfrost.hydro_backend.service;
+
+import dev.ivfrost.hydro_backend.entity.UserToken;
+import dev.ivfrost.hydro_backend.exception.*;
+import dev.ivfrost.hydro_backend.dto.*;
+import dev.ivfrost.hydro_backend.entity.User;
+import dev.ivfrost.hydro_backend.repository.UserTokenRepository;
+import dev.ivfrost.hydro_backend.repository.UserRepository;
+import dev.ivfrost.hydro_backend.security.JWTUtil;
+import dev.ivfrost.hydro_backend.util.DeviceDtoUtil;
+import dev.ivfrost.hydro_backend.util.RecoveryCodeUtil;
+import jakarta.transaction.Transactional;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.security.core.context.SecurityContext;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.util.Collections;
+import java.util.List;
+
+@Service
+public class UserService {
+
+    private final UserRepository userRepository;
+    private final UserTokenRepository userTokenRepository;
+    private final PasswordEncoder passwordEncoder;
+    private final EncoderService encoderService;
+    private final JWTUtil jwtUtil;
+    @Value("${security-code.secret}")
+    private String securityCodeSecret;
+
+    public UserService(UserRepository userRepository, UserTokenRepository userTokenRepository, PasswordEncoder passwordEncoder, EncoderService encoderService, JWTUtil jwtUtil) {
+        this.userRepository = userRepository;
+        this.userTokenRepository = userTokenRepository;
+        this.passwordEncoder = passwordEncoder;
+        this.encoderService = encoderService;
+        this.jwtUtil = jwtUtil;
+    }
+
+    /**
+     * Adds a new user with a specified role (admin only).
+     * Recovery codes are generated and the user is prompted to save them securely.
+     * @param req the user registration request DTO
+     * @param role the role to assign to the user
+     * @throws UsernameTakenException if the username is already taken
+     * @return the user registration response containing recovery codes
+     */
+    @Transactional
+    public UserRegisterResponse addUser(UserRegisterRequest req, User.Role role) {
+        if (userRepository.findByUsername(req.getUsername()).isPresent()) {
+            throw new UsernameTakenException(req.getUsername());
+        }
+        User user = convertRequestToUser(req);
+        user.setRole(role != null ? role : User.Role.USER); // Default to USER role if not specified
+        userRepository.save(user);
+        String[] recoveryCodes = RecoveryCodeUtil.generateRecoveryCodes(5);
+        for (String code : recoveryCodes) {
+            String encodedCode = encoderService.hmacSha256Encoder().apply(securityCodeSecret, code);
+
+            UserToken token = new UserToken();
+            token.setType(UserToken.TokenType.RECOVERY_CODE);
+            token.setToken(encodedCode);
+            token.setExpiryDate(null);
+            token.setUser(user);
+            userTokenRepository.save(token);
+        }
+        return new UserRegisterResponse(recoveryCodes);
+    }
+
+    /**
+     * Adds a new user with the default USER role (for self-registration).
+     * Recovery codes are generated and the user is prompted to save them securely.
+     * The first registered user is assigned the ADMIN role
+     * @param req the user registration request DTO
+     * @throws UsernameTakenException if the username is already taken
+     * @return the user registration response containing recovery codes
+     */
+    @Transactional
+    public UserRegisterResponse addUser(UserRegisterRequest req) {
+        boolean isFirstUser = userRepository.count() == 0;
+        User.Role role = isFirstUser ? User.Role.ADMIN : User.Role.USER; // First user is ADMIN, others are USER
+        return addUser(req, role);
+    }
+
+    /**
+     * Authenticates a user by email and password, returning a JWT token and refresh token if successful.
+     * @param req the user login request DTO
+     * @return the authentication response containing the JWT token and refresh token
+     * @throws UserNotFoundException if the user is not found
+     * @throws AuthWrongPasswordException if the password is incorrect
+     */
+    public AuthResponse authenticateUser(UserLoginRequest req) {
+        User user = userRepository.findByEmail(req.getEmail())
+                .orElseThrow(() -> new UserNotFoundException(req.getEmail()));
+        if (!passwordEncoder.matches(req.getPassword(), user.getPassword())) {
+            throw new AuthWrongPasswordException(req.getEmail());
+        }
+
+        user.setLastLogin(LocalDateTime.now().atZone(ZoneOffset.UTC).toInstant());
+        user.setActive(true);
+        userRepository.save(user);
+        return buildAuthResponse(user, "JWT token and refresh token generated successfully.");
+    }
+
+    /**
+     * Refreshes the JWT token and rotates the refresh token for the currently authenticated user.
+     * @return the authentication response containing the new JWT token and refresh token
+     * @throws UserNotFoundException if the user is not found
+     */
+    public AuthResponse refreshTokens() throws UserNotFoundException {
+        User user = getCurrentUserWithoutDevices();
+        return buildAuthResponse(user, "JWT token and refresh token refreshed successfully.");
+    }
+
+    /**
+     * Retrieves the currently authenticated user without devices (for performance).
+     * @return the authenticated user entity
+     * @throws UserNotFoundException if the user is not found
+     */
+    public User getCurrentUserWithoutDevices() {
+        Long userId = getCurrentUserId();
+        return userRepository.findById(userId)
+                .orElseThrow(() -> new UserNotFoundException(userId));
+    }
+
+    /**
+     * Retrieves the currently authenticated user with devices, or null if not authenticated.
+     * @return the authenticated user entity with devices, or null if not authenticated
+     */
+    public User getCurrentUser() {
+        if (!isUserAuthenticated()) {
+            return null;
+        }
+        try {
+            Long userId = getCurrentUserId();
+            return userRepository.findByIdWithDevices(userId).orElse(null);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * Retrieves the profile of the currently authenticated user as a response DTO.
+     * @return the user response DTO, or null if not authenticated
+     */
+    public UserResponse getCurrentUserProfile() {
+        return convertUserToResponse(getCurrentUser());
+    }
+
+    /**
+     * Retrieves a user by their unique ID (admin only, without devices).
+     * @param userId the ID of the user to retrieve
+     * @return the user entity
+     * @throws UserNotFoundException if the user is not found
+     */
+    public User getUserByIdWithoutDevices(Long userId) {
+        return userRepository.findById(userId).orElseThrow(() -> new UserNotFoundException(userId));
+    }
+
+    /**
+     * Retrieves a user by their unique ID with devices (admin only).
+     * @param userId the ID of the user to retrieve
+     * @return the user entity with devices
+     * @throws UserNotFoundException if the user is not found
+     */
+    public User getUserById(Long userId) {
+        return userRepository.findByIdWithDevices(userId).orElseThrow(() -> new UserNotFoundException(userId));
+    }
+
+    /**
+     * Retrieves a user profile by their unique ID as a response DTO (admin only).
+     * @param userId the ID of the user to retrieve
+     * @return the user response DTO
+     * @throws UserNotFoundException if the user is not found
+     */
+    public UserResponse getUserProfileById(Long userId) throws UserNotFoundException {
+        User user = getUserById(userId);
+        return convertUserToResponse(user);
+    }
+
+    /**
+     * Deletes the currently authenticated user (soft delete).
+     * @throws IllegalStateException if no authenticated user is found
+     */
+    public void deleteCurrentUser() throws IllegalStateException {
+        Long userId = getCurrentUserId();
+        deleteUserById(userId);
+    }
+
+    /**
+     * Deletes a user by their unique ID (admin only, soft delete).
+     * @param userId the ID of the user to delete
+     * @throws UserDeletedException if the user is already deleted
+     * @throws UserNotFoundException if the user is not found
+     */
+    public void deleteUserById(Long userId) {
+        User user = userRepository.findById(userId).orElseThrow(() -> new UserNotFoundException(userId));
+        if (user.isDeleted()) {
+            throw new UserDeletedException(userId);
+        }
+        user.setDeleted(true);
+        userRepository.save(user);
+    }
+
+    /**
+     * Resets the user's password using a recovery code provided to the user on registration.
+     * @param req the password reset request DTO containing the user email, recovery code and new password
+     * @throws RecoveryTokenNotFoundException if the recovery token is not found
+     * @throws UserNotFoundException if the user is not found
+     * @throws UserDeletedException if the user is deleted
+     */
+    @Transactional
+    public void resetPassword(PasswordResetRequest req) {
+        String encodedCode = encoderService.hmacSha256Encoder().apply(securityCodeSecret, req.getRecoveryCode());
+        UserToken recoveryToken = userTokenRepository
+                .findByTokenAndType(encodedCode, UserToken.TokenType.RECOVERY_CODE)
+                .orElseThrow(() -> new RecoveryTokenNotFoundException("Invalid recovery code."));
+
+        User user = recoveryToken.getUser();
+        if (user == null) {
+            throw new UserNotFoundException("User associated with the token not found.");
+        }
+        if (user.isDeleted()) {
+            throw new UserDeletedException(user.getId());
+        }
+        if (!user.getEmail().equals(req.getEmail())) {
+            throw new RecoveryTokenMismatchException("Recovery code does not match the provided email.");
+        }
+        user.setPassword(passwordEncoder.encode(req.getNewPassword()));
+        userRepository.save(user);
+        // Invalidate the used token
+        userTokenRepository.delete(recoveryToken);
+    }
+
+    /**
+     * Update the currently authenticated user's account settings.
+     * @param req the user update request DTO containing the fields to update
+     * @return the updated user response DTO
+     * @throws IllegalStateException if no authenticated user is found
+     * @throws UserNotFoundException if the user is not found
+     * @throws UserDeletedException if the user is deleted
+     */
+    @Transactional
+    public UserResponse updateCurrentUser(UserUpdateRequest req) {
+        Long userId = getCurrentUserId();
+        User user = userRepository.findById(userId).orElseThrow(() -> new UserNotFoundException(userId));
+        if (user.isDeleted()) {
+            throw new UserDeletedException(userId);
+        }
+        if (req.getFullName() != null && !req.getFullName().isBlank()) {
+            user.setFullName(req.getFullName());
+        }
+        if (req.getEmail() != null && !req.getEmail().isBlank()) {
+            user.setEmail(req.getEmail());
+        }
+        if (req.getPhoneNumber() != null) {
+            user.setPhoneNumber(req.getPhoneNumber());
+        }
+        if (req.getAddress() != null) {
+            user.setAddress(req.getAddress());
+        }
+        if (req.getProfilePictureUrl() != null) {
+            user.setProfilePictureUrl(req.getProfilePictureUrl());
+        }
+        if (req.getPreferredLanguage() != null && !req.getPreferredLanguage().isBlank()) {
+            user.setPreferredLanguage(req.getPreferredLanguage());
+        }
+        if (req.getSettings() != null) {
+            user.setSettings(req.getSettings());
+        }
+        userRepository.save(user);
+        return convertUserToResponse(user);
+    }
+
+    /*--------------------------*/
+    /*      Helper Methods      */
+    /*--------------------------*/
+
+    /**
+     * Builds an AuthResponse with both tokens and a message.
+     * @param user the user entity
+     * @param message the message to include
+     * @return the AuthResponse containing both tokens and the message
+     */
+    private AuthResponse buildAuthResponse(User user, String message) {
+        String token = generateToken(user);
+        String refreshToken = generateRefreshToken(user);
+        return new AuthResponse(token, refreshToken, message);
+    }
+
+    /**
+     * Checks if a user is authenticated in the security context.
+     * @return true if a user is authenticated, false otherwise
+     */
+    private boolean isUserAuthenticated() {
+        SecurityContext context = SecurityContextHolder.getContext();
+        return context.getAuthentication() != null && context.getAuthentication().isAuthenticated();
+    }
+
+    /**
+     * Retrieves the ID of the currently authenticated user from the security context.
+     * @return the user ID
+     * @throws IllegalStateException if no authenticated user is found
+     */
+    private Long getCurrentUserId() {
+        if (isUserAuthenticated()) {
+            String name = SecurityContextHolder.getContext().getAuthentication().getName();
+            if ("anonymousUser".equals(name)) {
+                throw new IllegalStateException("No authenticated user found in security context.");
+            }
+            return Long.parseLong(name);
+        } else {
+            throw new IllegalStateException("No authenticated user found in security context.");
+        }
+    }
+
+    /**
+     * Converts a UserRegisterRequest DTO to a User entity.
+     * @param req the user registration request DTO
+     * @return the user entity
+     */
+    private User convertRequestToUser(UserRegisterRequest req) {
+        String encodedPassword = passwordEncoder.encode(req.getPassword()); // Bcrypt password encoding
+        User user = new User();
+        user.setUsername(req.getUsername());
+        user.setPassword(encodedPassword);
+        user.setEmail(req.getEmail());
+        user.setFullName(req.getFullName());
+        user.setPreferredLanguage(req.getPreferredLanguage());
+        return user;
+    }
+
+    /**
+     * Converts a User entity to a UserResponse DTO.
+     * @param user the user entity
+     * @return the user response DTO
+     */
+    private UserResponse convertUserToResponse(User user) {
+        if (user == null) {
+            return null;
+        }
+
+        UserResponse response = new UserResponse();
+        response.setId(user.getId());
+        response.setUsername(user.getUsername());
+        response.setFullName(user.getFullName());
+        response.setEmail(user.getEmail());
+        response.setProfilePictureUrl(user.getProfilePictureUrl());
+        response.setPhoneNumber(user.getPhoneNumber());
+        response.setAddress(user.getAddress());
+        response.setCreatedAt(user.getCreatedAt());
+        response.setUpdatedAt(user.getUpdatedAt());
+        response.setLastLogin(user.getLastLogin());
+        response.setRole(user.getRole());
+        response.setPreferredLanguage(user.getPreferredLanguage());
+        response.setSettings(user.getSettings());
+
+        List<DeviceResponse> userDevices = user.getDevices() != null ?
+            DeviceDtoUtil.convertDevicesToResponse(user.getDevices()) :
+            Collections.emptyList();
+        response.setDevices(userDevices);
+
+        return response;
+    }
+
+    /**
+     * Generates a JWT token for a given user.
+     * @param user the user entity
+     * @return a String containing the JWT token
+     * @throws UserDeletedException if the user is deleted
+     */
+    private String generateToken(User user)  {
+        if (user.isDeleted()) {
+            throw new UserDeletedException(user.getId());
+        }
+        return jwtUtil.generateToken(user);
+    }
+
+    /**
+     * Generates a refresh JWT token for a given user.
+     * @param user the user entity
+     * @return a String containing the refresh JWT token
+     * @throws UserDeletedException if the user is deleted
+     */
+    private String generateRefreshToken(User user) {
+        if (user.isDeleted()) {
+            throw new UserDeletedException(user.getId());
+        }
+        return jwtUtil.generateRefreshToken(user);
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/service/UserTokenService.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/service/UserTokenService.java
@@ -0,0 +1,35 @@
+package dev.ivfrost.hydro_backend.service;
+
+import dev.ivfrost.hydro_backend.entity.UserToken;
+import dev.ivfrost.hydro_backend.exception.RecoveryTokenMismatchException;
+import dev.ivfrost.hydro_backend.exception.RecoveryTokenNotFoundException;
+import dev.ivfrost.hydro_backend.repository.UserTokenRepository;
+import lombok.Data;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+@Data
+@Service
+public class UserTokenService {
+
+    private final UserTokenRepository userTokenRepository;
+    private final EncoderService encoderService;
+
+    @Value("${security-code.secret}")
+    private String securityCodeSecret;
+
+    public UserTokenService(UserTokenRepository userTokenRepository, EncoderService encoderService) {
+        this.userTokenRepository = userTokenRepository;
+        this.encoderService = encoderService;
+    }
+
+    public boolean isRecoveryCodeValid(String rawCode, String email) {
+        String encodedCode = encoderService.hmacSha256Encoder().apply(securityCodeSecret, rawCode);
+        UserToken userToken = userTokenRepository.findByTokenAndType(encodedCode, UserToken.TokenType.RECOVERY_CODE)
+                .orElseThrow(() -> new RecoveryTokenNotFoundException("Recovery code not found"));
+        if (!userToken.getUser().getEmail().equals(email)) {
+            throw new RecoveryTokenMismatchException("Recovery code does not match the provided email");
+        }
+        return true;
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/util/DeviceDtoUtil.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/util/DeviceDtoUtil.java
@@ -0,0 +1,48 @@
+package dev.ivfrost.hydro_backend.util;
+
+import dev.ivfrost.hydro_backend.dto.DeviceResponse;
+import dev.ivfrost.hydro_backend.entity.Device;
+
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+public class DeviceDtoUtil {
+
+    /**
+     * Converts a Device entity to a DeviceResponse DTO.
+     *
+     * @param device the device entity
+     * @return the device response DTO
+     */
+    public static DeviceResponse convertDeviceToResponse(Device device) {
+        if (device == null) return null;
+        return new DeviceResponse(
+                device.getId(),
+                device.getName(),
+                device.getLocation(),
+                device.getFirmware(),
+                device.getTechnicalName(),
+                device.getIp(),
+                device.getCreatedAt(),
+                device.getUpdatedAt(),
+                device.getLinkedAt(),
+                device.getLastSeen(),
+                device.getUser(),
+                device.getDisplayOrder() != null ? device.getDisplayOrder() : 0
+        );
+    }
+
+    /**
+     * Converts a list of Device entities to a list of DeviceResponse DTOs.
+     *
+     * @param devices the list of device entities
+     * @return the list of device response DTOs
+     */
+    public static List<DeviceResponse> convertDevicesToResponse(List<Device> devices) {
+        return devices.stream()
+                .map(DeviceDtoUtil::convertDeviceToResponse)
+                .collect(Collectors.toList());
+    }
+}
+
--- a/src/main/java/dev/ivfrost/hydro_backend/util/RateLimitUtils.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/util/RateLimitUtils.java
@@ -0,0 +1,59 @@
+package dev.ivfrost.hydro_backend.util;
+
+import dev.ivfrost.hydro_backend.entity.User;
+import io.github.bucket4j.Bandwidth;
+import io.github.bucket4j.Bucket;
+import jakarta.servlet.http.HttpServletRequest;
+import lombok.AllArgsConstructor;
+import lombok.NoArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import java.time.Duration;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Component
+@AllArgsConstructor
+@NoArgsConstructor
+public class RateLimitUtils {
+
+    private ConcurrentHashMap<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+    public Optional<Bucket> getBucketByUserOrIp(User user, String ipAddress) {
+        if (user != null) {
+            return Optional.of(getBucketByUserId(user.getId().toString()));
+        } else if (ipAddress != null && !ipAddress.isEmpty()) {
+            return Optional.of(getBucketByIp(ipAddress));
+        } else {
+            return Optional.empty();
+        }
+    }
+
+    private Bucket getBucketByIp(String ipAddres) {
+        return buckets.computeIfAbsent(ipAddres, k -> {
+            Bandwidth limit = Bandwidth.builder()
+                    .capacity(10)
+                    .refillGreedy(10, Duration.ofMinutes(1))
+                    .build();
+            return Bucket.builder().addLimit(limit).build();
+        });
+    }
+
+    private Bucket getBucketByUserId(String userId) {
+        return buckets.computeIfAbsent(userId, k -> {
+            Bandwidth limit = Bandwidth.builder()
+                    .capacity(20)
+                    .refillGreedy(20, Duration.ofMinutes(1))
+                    .build();
+            return Bucket.builder().addLimit(limit).build();
+        });
+    }
+
+    public static String extractClientIp(HttpServletRequest request) {
+        String xff = request.getHeader("X-Forwarded-For");
+        if (xff != null && !xff.isEmpty()) {
+            return xff.split(",")[0].trim();
+        }
+        return request.getRemoteAddr();
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/util/RecoveryCodeUtil.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/util/RecoveryCodeUtil.java
@@ -0,0 +1,32 @@
+package dev.ivfrost.hydro_backend.util;
+
+import dev.ivfrost.hydro_backend.repository.UserTokenRepository;
+import dev.ivfrost.hydro_backend.service.EncoderService;
+import lombok.AllArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+
+import java.security.SecureRandom;
+
+@AllArgsConstructor
+public class RecoveryCodeUtil {
+    private static final String CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*";
+    private static final SecureRandom RANDOM = new SecureRandom();
+    private static final int RECOVERY_CODE_LENGTH = 16;
+
+    public static String generateRecoveryCode() {
+        StringBuilder code = new StringBuilder(RECOVERY_CODE_LENGTH);
+        for (int i = 0; i < RECOVERY_CODE_LENGTH; i++) {
+            int idx = RANDOM.nextInt(CHARSET.length());
+            code.append(CHARSET.charAt(idx));
+        }
+        return code.toString();
+    }
+
+    public static String[] generateRecoveryCodes(int count) {
+        String[] codes = new String[count];
+        for (int i = 0; i < count; i++) {
+            codes[i] = generateRecoveryCode();
+        }
+        return codes;
+    }
+}
--- a/src/main/java/dev/ivfrost/hydro_backend/util/ValidationUtils.java
+++ b/src/main/java/dev/ivfrost/hydro_backend/util/ValidationUtils.java
@@ -0,0 +1,42 @@
+package dev.ivfrost.hydro_backend.util;
+
+import dev.ivfrost.hydro_backend.repository.UserRepository;
+import dev.ivfrost.hydro_backend.service.UserService;
+import jakarta.validation.Validation;
+import lombok.AllArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.Map;
+import java.util.stream.Collectors;
+
+@AllArgsConstructor
+@Service
+public class ValidationUtils {
+
+    private final UserRepository userRepository;
+
+    public Map<String, Object> getClassValidationRules(Class<?> className) {
+        var validator = Validation.buildDefaultValidatorFactory().getValidator();
+        var beanDescriptor = validator.getConstraintsForClass(className);
+        return beanDescriptor.getConstrainedProperties()
+                .stream()
+                .collect(Collectors.toMap(
+                        prop -> prop.getPropertyName(),
+                        prop -> prop.getConstraintDescriptors()
+                                .stream()
+                                .map(descriptor -> Map.of(
+                                        "annotation", descriptor.getAnnotation().annotationType().getSimpleName(),
+                                        "attributes", descriptor.getAttributes()
+                                ))
+                                .collect(Collectors.toList())
+                ));
+    }
+
+    public boolean isUsernameAvailable(String username) {
+        return !userRepository.existsByUsername(username);
+    }
+
+    public boolean isEmailAvailable(String email) {
+        return !userRepository.existsByEmail(email);
+    }
+}
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -0,0 +1,31 @@
+spring:
+  application:
+    name: hydro-backend
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+  datasource:
+    url: jdbc:postgresql://${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+    username: ${POSTGRES_USER}
+    password: ${POSTGRES_PASSWORD}
+    driver-class-name: org.postgresql.Driver
+
+security-code:
+  secret: ${SECURITY_CODE_SECRET} # used to store security codes in encrypted form
+jwt:
+  secret: ${JWT_SECRET}
+  expiration-ms: 3600000 # 1 hour
+  refresh-expiration-ms: 86400000 # 24 hours
+
+device:
+  secret: ${DEVICE_SECRET}
+
+springdoc:
+  swagger-ui:
+    path: /docs
+    url: http://localhost:8080/v3/api-docs
+
+server:
+  forward-headers-strategy: framework
+  servlet:
+    context-path: /
--- a/src/test/java/dev/ivfrost/hydro_backend/HydroBackendApplicationTests.java
+++ b/src/test/java/dev/ivfrost/hydro_backend/HydroBackendApplicationTests.java
@@ -0,0 +1,13 @@
+package dev.ivfrost.hydro_backend;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+class HydroBackendApplicationTests {
+
+	@Test
+	void contextLoads() {
+	}
+
+}
--- a/test-build.sh
+++ b/test-build.sh
@@ -0,0 +1,2 @@
+docker run -p 8080:8080 --env-file .env hydro-backend:0.0.1-SNAPSHOT
+
				`@@ -0,0 +1,2 @@`
				`docker run -p 8080:8080 --env-file .env hydro-backend:0.0.1-SNAPSHOT`