admin/_docs/02_document/components/05_admin_api/description.md

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