admin/_docs/01_solution/solution.md

Azaion Admin API — Solution

1. Product Solution Description

The Azaion Admin API is a centralized backend service that manages the Azaion Suite ecosystem — a platform for AI-powered annotation workflows. The API provides:

• User lifecycle management — registration, authentication, role assignment, enabling/disabling accounts
• Hardware-bound access control — ties software resources to specific physical devices via hardware fingerprint verification
• Encrypted resource distribution — delivers DLLs, AI models, and installers encrypted per-user using AES-256-CBC, with keys derived from the user's credentials and hardware identity
• Role-based authorization — hierarchical role system (Operator → Validator → CompanionPC → Admin → ResourceUploader → ApiAdmin) controlling access to different API operations

graph LR
    AdminPanel["Admin Web Panel<br/>(admin.azaion.com)"] -->|REST API| API["Azaion Admin API"]
    SuiteClient["Azaion Suite Client<br/>(Desktop App)"] -->|REST API| API
    API -->|linq2db| DB["PostgreSQL"]
    API -->|File I/O| FS["Server Filesystem<br/>(Resources, Installers)"]

2. Architecture

Component Architecture

Component	Responsibility	Key Interfaces
Data Layer	DB access, entities, ORM mapping, caching	IDbFactory, ICache
User Management	User CRUD, hardware binding, role management	IUserService (10 methods)
Auth & Security	JWT tokens, hashing, AES encryption/decryption	IAuthService, Security (static)
Resource Management	File upload/download, encrypted delivery	IResourcesService
Admin API	17 HTTP endpoints, middleware, DI composition	ASP.NET Core Minimal API

Solution Details

Solution	Tools	Advantages	Limitations	Security	Fit
ASP.NET Core Minimal API (.NET 10.0)	C#, Kestrel	Lightweight, strong typing, cross-platform, fast	All endpoints in single file, no controller separation	Built-in auth middleware	Excellent for small-medium API
PostgreSQL + linq2db	Npgsql 10.0.1, linq2db 5.4.1	Lightweight ORM, LINQ-native queries, read/write connection separation	No migration framework, manual schema via SQL scripts	DB-level role separation (reader/admin)	Good for simple data model
JWT Bearer Authentication	System.IdentityModel.Tokens.Jwt 7.1.2	Stateless, standard, well-supported	Token revocation requires additional infrastructure	HMAC-SHA256 signing, full validation	Standard choice
AES-256-CBC Per-User Encryption	System.Security.Cryptography	Strong encryption, per-user key derivation from credentials + hardware	Full file encryption in memory (MemoryStream), limits to available RAM	Random IV per encryption, SHA-256 derived key	Fit for DLL/model distribution
Hardware Fingerprint Binding	Custom (SHA-384 hash with static salt)	Ties resources to specific devices	Single-device lock, admin reset needed for hardware changes	Salted hash comparison	Domain-specific requirement
LazyCache In-Memory Caching	LazyCache 2.4.0	Simple async get-or-add pattern	Not distributed, 4-hour hardcoded TTL	N/A	Adequate for single-instance deployment
Docker + Woodpecker CI	Docker multi-stage, ARM64	Reproducible builds, private registry	ARM64 only, no test step in CI, no orchestration	Private registry	Basic but functional

3. Testing Strategy

Existing Tests

Test	Type	Coverage	Framework
SecurityTest.EncryptDecryptTest	Unit	AES encrypt/decrypt round-trip (small data)	xUnit + FluentAssertions
SecurityTest.EncryptDecryptLargeFileTest	Unit	AES encrypt/decrypt round-trip (~400 MB file)	xUnit + FluentAssertions
UserServiceTest.CheckHardwareHashTest	Integration	Hardware hash validation against live DB	xUnit

Test Gaps

• No tests for: AuthService, ResourcesService, UserService (registration, login, CRUD), API endpoints (integration), FluentValidation validators
• UserServiceTest depends on a live remote database with hardcoded credentials — not portable or CI-friendly
• No CI test step in the Woodpecker pipeline

4. References

Artifact	Path	Purpose
Dockerfile	./Dockerfile	Multi-stage container build
CI Pipeline	.woodpecker/build-arm.yml	ARM64 build + push
DB Schema	env/db/02_structure.sql	Table DDL + seed data
DB Permissions	env/db/01_permissions.sql	Role creation
DB Migration	env/db/03_add_timestamp_columns.sql	Schema evolution
App Config	Azaion.AdminApi/appsettings.json	Default config values
Deploy Script	deploy.cmd	Manual docker build + push
Environment Setup	env/api/env.ps1	Windows env var setup