mirror of
https://github.com/azaion/admin.git
synced 2026-04-22 22:16:33 +00:00
Oleksandr Bezdieniezhnykh
72 lines
4.8 KiB
Markdown
72 lines
4.8 KiB
Markdown
# 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 |
|