admin/_docs/02_document/components/02_user_management/description.md

User Management

1. High-Level Overview

Purpose: Full user lifecycle management — registration, credential validation, hardware binding, role changes, account enable/disable, and deletion.

Architectural Pattern: Service layer — stateless business logic operating on the Data Layer through IDbFactory.

Upstream dependencies: Data Layer (IDbFactory, ICache, User entity), Security & Cryptography (hashing).

Downstream consumers: Admin API (endpoint handlers), Authentication (GetByEmail).

2. Internal Interfaces

Interface: IUserService

Method	Input	Output	Async	Error Types
RegisterUser	RegisterUserRequest, CancellationToken	void	Yes	BusinessException(EmailExists)
ValidateUser	LoginRequest, CancellationToken	User	Yes	BusinessException(NoEmailFound, WrongPassword)
GetByEmail	string? email, CancellationToken	User?	Yes	ArgumentNullException
UpdateHardware	string email, string? hardware, CancellationToken	void	Yes	None
UpdateQueueOffsets	string email, UserQueueOffsets, CancellationToken	void	Yes	None
GetUsers	string? searchEmail, RoleEnum? searchRole, CancellationToken	IEnumerable<User>	Yes	None
CheckHardwareHash	User, string hardware, CancellationToken	string (hash)	Yes	BusinessException(HardwareIdMismatch)
ChangeRole	string email, RoleEnum, CancellationToken	void	Yes	None
SetEnableStatus	string email, bool, CancellationToken	void	Yes	None
RemoveUser	string email, CancellationToken	void	Yes	None

Input DTOs:

RegisterUserRequest:
  Email: string (required) — validated: min 8 chars, valid email format
  Password: string (required) — validated: min 8 chars
  Role: RoleEnum (required)

LoginRequest:
  Email: string (required)
  Password: string (required)

SetHWRequest:
  Email: string (required, validated: not empty)
  Hardware: string? (optional — null clears hardware)

SetUserQueueOffsetsRequest:
  Email: string (required)
  Offsets: UserQueueOffsets (required)

3. External API Specification

N/A — exposed through Admin API component.

4. Data Access Patterns

Queries

Query	Frequency	Hot Path	Index Needed
User by email (cached)	High	Yes	Yes
User list with filters	Medium	No	No
User insert (registration)	Low	No	No
User update (hardware, role, config, status)	Medium	No	No
User delete	Low	No	No

Caching Strategy

Data	Cache Type	TTL	Invalidation
User by email	In-memory (via ICache)	4 hours	After UpdateHardware, UpdateQueueOffsets, CheckHardwareHash (first login)

5. Implementation Details

State Management: Stateless — all state in PostgreSQL + in-memory cache.

Key Dependencies:

Library	Version	Purpose
FluentValidation	11.10.0	Request validation (auto-discovered)

Error Handling Strategy:

• Domain errors thrown as BusinessException with specific ExceptionEnum codes.
• GetByEmail throws ArgumentNullException for null/whitespace email.
• Database errors propagate from IDbFactory.
• Write operations use RunAdmin (admin connection); reads use Run (reader connection).

6. Extensions and Helpers

Helper	Purpose	Used By
Security.ToHash	Password hashing (SHA-384)	RegisterUser, ValidateUser
Security.GetHWHash	Hardware fingerprint hashing	CheckHardwareHash
QueryableExtensions.WhereIf	Conditional LINQ filters	GetUsers

7. Caveats & Edge Cases

Known limitations:

• No pagination on GetUsers — returns all matching users.
• CheckHardwareHash auto-stores hardware on first access (no explicit admin approval step).
• RemoveUser is a hard delete, not soft delete.

Potential race conditions:

• Concurrent RegisterUser calls with the same email: both could pass the existence check before insert. Mitigated by database unique constraint on email (if one exists).
• CheckHardwareHash first-login path: concurrent requests could trigger multiple hardware updates.

Performance bottlenecks:

• GetUsers loads full user objects including UserConfig JSON; for large user bases, projection would be more efficient.

8. Dependency Graph

Must be implemented after: Data Layer, Security & Cryptography.

Can be implemented in parallel with: Resource Management.

Blocks: Authentication (uses GetByEmail), Admin API.

9. Logging Strategy

No explicit logging in UserService.

Modules Covered

• Services/UserService
• Common/Requests/LoginRequest
• Common/Requests/RegisterUserRequest
• Common/Requests/SetHWRequest
• Common/Requests/SetUserQueueOffsetsRequest