# Resource Management

> **Cycle 1 (2026-05-13) note** — AZ-197 removed the `Hardware` field from `GetResourceRequest` and removed `CheckResourceRequest` and `POST /resources/check` entirely. AZ-183 introduced an OTA update path (`POST /get-update`, `POST /resources/publish`, `IResourceUpdateService`, `Resource` entity, `resources` table, `ResourcesConfig.EncryptionMasterKey`) but it was reverted later the same day after the security audit (finding F-1) — the OTA delivery model itself was deemed obsolete.
>
> **Cycle 2 (2026-05-14) note** — the encrypted-download endpoint (`POST /resources/get/{dataFolder?}`) and both installer endpoints (`GET /resources/get-installer[/stage]`) were removed as obsolete. With them went `ResourcesService.GetEncryptedResource` / `GetInstaller`, `GetResourceRequest` (and `WrongResourceName = 50`), and the `ResourcesConfig.SuiteInstallerFolder` / `SuiteStageInstallerFolder` properties + their env-var rows. The component is now upload + list + clear only and no longer depends on Authentication & Security for encryption primitives.

## 1. High-Level Overview

**Purpose**: filesystem-backed storage — upload, list, clear. Owned by `IResourcesService`.

**Architectural Pattern**: a single service over the local filesystem. No DB access, no cache.

**Upstream dependencies**: Data Layer (`ResourcesConfig`).

**Downstream consumers**: Admin API (resource endpoints).

## 2. Internal Interfaces

### Interface: IResourcesService

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `SaveResource` | `string? dataFolder, IFormFile data, CancellationToken` | void | Yes | `BusinessException(NoFileProvided)` |
| `ListResources` | `string? dataFolder, string? search, CancellationToken` | `IEnumerable<string>` | Yes | `DirectoryNotFoundException` |
| `ClearFolder` | `string? dataFolder` | void | No | None |

**Removed**:
- `GetEncryptedResource` — removed in cycle 2 with the encrypted-download endpoint.
- `GetInstaller` — removed in cycle 2 with the installer endpoints.

**Removed DTOs**:
- `GetResourceRequest` — removed in cycle 2 (file deleted).
- `CheckResourceRequest` — removed by AZ-197 (cycle 1).
- `GetUpdateRequest`, `PublishResourceRequest` — removed in the post-cycle-1 AZ-183 revert.

## 3. External API Specification

N/A — exposed through Admin API.

## 4. Data Access Patterns

`ResourcesService` is filesystem-only — no DB access, no cache.

| Source | Service | Pattern |
|--------|---------|---------|
| Filesystem (`ResourcesConfig.ResourcesFolder`) | `ResourcesService` | Direct read/write/delete |

### Storage Estimates

- **Filesystem**: AI models, DLLs, etc. — potentially hundreds of MB per file.

## 5. Implementation Details

**State Management**: stateless — reads/writes directly to filesystem.

**Key Dependencies**: none beyond BCL (System.IO).

**Error Handling Strategy**:
- `SaveResource` throws `BusinessException(NoFileProvided)` for null uploads.
- Missing files/directories throw standard .NET I/O exceptions.
- `ClearFolder` silently returns if directory doesn't exist.

## 6. Extensions and Helpers

None remaining after the cycle-2 removal of `Security.EncryptTo` and `Security.GetApiEncryptionKey`.

## 7. Caveats & Edge Cases

**Known limitations** (security-audit findings):
- **F-2 (High)** — no path traversal protection: `dataFolder` parameter is concatenated directly with `ResourcesFolder`. A malicious `dataFolder` like `../../etc` could access arbitrary filesystem paths. Filed as separate ticket.
- `SaveResource` deletes existing file before writing — no versioning or backup.
- `ListResources` wraps a synchronous `DirectoryInfo.GetFiles` in `Task.FromResult` — not truly async.

**Performance bottlenecks**:
- `ClearFolder` iterates and deletes files synchronously.

## 8. Dependency Graph

**Must be implemented after**: Data Layer (ResourcesConfig).

**Can be implemented in parallel with**: User Management, Authentication & Security.

**Blocks**: Admin API.

## 9. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| INFO | Successful file save | `Resource {data.FileName} Saved Successfully` |

**Log format**: string interpolation via Serilog (security audit F-12 hygiene item: convert to structured form).

**Log storage**: console + rolling file (via Serilog configured in Program.cs).

## Modules Covered
- `Services/ResourcesService` (post-cycle-2 — only `SaveResource` / `ListResources` / `ClearFolder` remain)
- `Common/Configs/ResourcesConfig` (post-cycle-2 — only `ResourcesFolder` remains)