# 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

```mermaid
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 |