Update documentation

docs/diagrams/authentication-flow.puml

@@ -0,0 +1,72 @@
+@startuml authentication-flow
+!theme plain
+skinparam backgroundColor #FFFFFF
+skinparam defaultFontName Arial
+
+title User Authentication Flow
+
+actor User
+participant "API\nController" as API
+participant "Service.Auth" as AuthSvc
+participant "Password\nHasher" as PwdHash
+participant "Repository" as Repo
+participant "JWT\nProvider" as JWT
+database "SQL Server\nStored Procedures" as DB
+
+== Registration ==
+User -> API: POST /api/auth/register
+activate API
+API -> AuthSvc: RegisterAsync(username, email, password)
+activate AuthSvc
+AuthSvc -> AuthSvc: Validate input
+AuthSvc -> PwdHash: HashPassword(password)
+activate PwdHash
+PwdHash -> PwdHash: Argon2id\n(64MB, 4 iterations)
+return hash + salt
+AuthSvc -> Repo: CreateUserWithCredential(user, hash)
+activate Repo
+Repo -> DB: EXEC USP_RegisterUser
+activate DB
+DB -> DB: Create UserAccount\nCreate UserCredential\nCreate UserVerification
+return userId
+return userId
+AuthSvc -> JWT: GenerateToken(userId, username)
+activate JWT
+JWT -> JWT: HS256 signing\nInclude claims
+return JWT token
+return RegisterResult{token, userId}
+API -> User: 201 Created + JWT
+deactivate API
+
+== Login ==
+User -> API: POST /api/auth/login
+activate API
+API -> AuthSvc: LoginAsync(username, password)
+activate AuthSvc
+AuthSvc -> Repo: GetUserCredential(username)
+activate Repo
+Repo -> DB: EXEC USP_GetUserAccountByUsername
+activate DB
+return user + credential
+return UserCredential
+AuthSvc -> PwdHash: VerifyPassword(password, hash, salt)
+activate PwdHash
+PwdHash -> PwdHash: Argon2id verify
+return isValid
+alt Password Valid
+  AuthSvc -> JWT: GenerateToken(userId, username)
+  activate JWT
+  return JWT token
+  AuthSvc -> Repo: UpdateLastLogin(userId)
+  activate Repo
+  Repo -> DB: Update LastLogin
+  return
+  return LoginResult{token, userId}
+  API -> User: 200 OK + JWT
+else Invalid Credentials
+  return AuthenticationException
+  API -> User: 401 Unauthorized
+end
+deactivate API
+
+@enduml