# Admin API

## 1. High-Level Overview

**Purpose**: HTTP API entry point — configures DI, middleware pipeline, authentication, authorization, CORS, Swagger, and defines all REST endpoints using ASP.NET Core Minimal API.

**Architectural Pattern**: Composition root + Minimal API endpoints — top-level statements configure the application and map HTTP routes to service methods.

**Upstream dependencies**: User Management (IUserService), Authentication & Security (IAuthService, Security), Resource Management (IResourcesService), Data Layer (IDbFactory, ICache, configs).

**Downstream consumers**: None (top-level entry point, consumed by HTTP clients).

## 2. Internal Interfaces

### BusinessExceptionHandler

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `TryHandleAsync` | `HttpContext, Exception, CancellationToken` | `bool` | Yes | None |

Converts `BusinessException` to HTTP 409 JSON response: `{ ErrorCode: int, Message: string }`.

## 3. External API Specification

### Authentication
| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/login` | POST | Anonymous | Validates credentials, returns JWT |

### User Management
| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/users` | POST | ApiAdmin | Creates a new user |
| `/users/current` | GET | Authenticated | Returns current user |
| `/users` | GET | ApiAdmin | Lists users (optional email/role filters) |
| `/users/hardware/set` | PUT | ApiAdmin | Sets user hardware |
| `/users/queue-offsets/set` | PUT | Authenticated | Updates queue offsets |
| `/users/{email}/set-role/{role}` | PUT | ApiAdmin | Changes user role |
| `/users/{email}/enable` | PUT | ApiAdmin | Enables user |
| `/users/{email}/disable` | PUT | ApiAdmin | Disables user |
| `/users/{email}` | DELETE | ApiAdmin | Removes user |

### Resource Management
| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/resources/{dataFolder?}` | POST | Authenticated | Uploads a file (up to 200 MB) |
| `/resources/list/{dataFolder?}` | GET | Authenticated | Lists files |
| `/resources/clear/{dataFolder?}` | POST | ApiAdmin | Clears folder |
| `/resources/get/{dataFolder?}` | POST | Authenticated | Downloads encrypted resource |
| `/resources/get-installer` | GET | Authenticated | Downloads production installer |
| `/resources/get-installer/stage` | GET | Authenticated | Downloads staging installer |
| `/resources/check` | POST | Authenticated | Validates hardware |

### Authorization Policies
- **apiAdminPolicy**: requires `ApiAdmin` role (used on most admin endpoints)
- **apiUploaderPolicy**: requires `ResourceUploader` or `ApiAdmin` role (**defined but never applied to any endpoint — dead code**)

### CORS
- Allowed origins: `https://admin.azaion.com`, `http://admin.azaion.com`
- All methods/headers, credentials allowed

## 4. Data Access Patterns

No direct data access — delegates to service components.

## 5. Implementation Details

**State Management**: Stateless — ASP.NET Core request pipeline.

**Key Dependencies**:

| Library | Version | Purpose |
|---------|---------|---------|
| Swashbuckle.AspNetCore | 10.1.4 | Swagger/OpenAPI documentation |
| FluentValidation.AspNetCore | 11.3.0 | Request validation pipeline |
| Serilog | 4.1.0 | Structured logging |
| Serilog.Sinks.Console | 6.0.0 | Console log output |
| Serilog.Sinks.File | 6.0.0 | Rolling file log output |

**Error Handling Strategy**:
- `BusinessException` → `BusinessExceptionHandler` → HTTP 409 with JSON body.
- `UnauthorizedAccessException` → thrown in resource endpoints when current user is null.
- `FileNotFoundException` → thrown when installer not found.
- FluentValidation errors → automatic 400 Bad Request via middleware.
- Unhandled exceptions → default ASP.NET Core exception handling.

## 6. Extensions and Helpers

None.

## 7. Caveats & Edge Cases

**Known limitations**:
- All endpoints are defined in a single `Program.cs` file — no route grouping or controller separation.
- Swagger UI only available in Development environment.
- CORS origins are hardcoded (not configurable).
- Antiforgery disabled for resource upload endpoint.
- Root URL (`/`) redirects to `/swagger`.

**Performance bottlenecks**:
- Kestrel max request body: 200 MB — allows large file uploads but could be a memory concern.

## 8. Dependency Graph

**Must be implemented after**: All other components (composition root).

**Can be implemented in parallel with**: Nothing — depends on all services.

**Blocks**: Nothing.

## 9. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| WARN | Business exception caught | `BusinessExceptionHandler` logs the exception |
| INFO | Serilog minimum level | General application events |

**Log format**: Serilog structured logging with context enrichment.

**Log storage**: Console + rolling file (`logs/log.txt`, daily rotation).

## Modules Covered
- `AdminApi/Program`
- `AdminApi/BusinessExceptionHandler`