[AZ-189] [AZ-190] [AZ-191] [AZ-192] [AZ-193] [AZ-194] [AZ-195] Add e2e blackbox test suite

Made-with: Cursor

_docs/00_problem/problem.md

@@ -0,0 +1,38 @@
+# Problem Statement
+
+## What is this system?
+
+The Azaion Admin API is the backend management service for the Azaion Suite — a platform for AI-powered data annotation workflows. The suite includes desktop client software (annotators, dataset explorers) that must be securely distributed and controlled.
+
+## What problem does it solve?
+
+The Azaion platform needs to:
+
+1. **Control who can use the software** — only registered, authorized users should access the annotation tools. Different users have different permission levels (operators can annotate, validators can review, admins can manage everything).
+
+2. **Bind software to specific hardware** — prevent unauthorized copying or redistribution of proprietary software components (AI models, DLLs). Each user's resources must be tied to their specific physical machine.
+
+3. **Securely distribute software updates** — deliver installers and resource files (AI models, DLLs) to authorized users, encrypted such that only the intended user on the intended hardware can use them.
+
+4. **Manage the user base** — admins need to create accounts, assign roles, enable/disable users, reset hardware bindings, and track activity (last login).
+
+5. **Support annotation queue coordination** — users participate in annotation queues and need to maintain per-user offset tracking to resume work across sessions.
+
+## Who are the users?
+
+| User Type | Role(s) | What They Do |
+|-----------|---------|-------------|
+| Annotators | Operator | Use the desktop client to annotate data; submit annotations to queues |
+| Validators | Validator | Review annotations from queues, explore datasets |
+| Companion PCs | CompanionPC | Automated annotation devices (e.g., OrangePi) |
+| Resource Uploaders | ResourceUploader | Upload DLLs and AI models to the server |
+| System Administrators | ApiAdmin | Full control: user management, resource management, all operations |
+
+## How does it work at a high level?
+
+1. An admin creates user accounts via the API (or admin web panel at admin.azaion.com)
+2. Users authenticate via email/password and receive a JWT token
+3. On first resource access, the client sends its hardware fingerprint, which is stored for the user
+4. When downloading resources, the API encrypts files using a key derived from the user's email, password, and hardware hash — only that specific user on that specific machine can decrypt
+5. Installers (production and staging) are distributed to authenticated users without per-user encryption
+6. Users maintain annotation queue offsets that persist across sessions