pos-system/services/storage-service-net/SERVICE_DOCS.md

StorageService - Service Documentation

Auto-generated from source code audit on 2026-03-13

Overview

StorageService is a file storage microservice providing S3-compatible object storage with support for direct uploads, multipart uploads, file sharing, file versioning, logical folders, and per-user storage quotas. It supports two storage backends: MinIO (primary) and Aliyun OSS.

• Port: 5002 (Development)
• Database: storage_service (PostgreSQL / Neon)
• Storage Backend: MinIO (S3-compatible) at 167.114.174.113:9000
• Cache: Redis at 167.114.174.113:6379
• Default Bucket: goodgo
• Max File Size: 100MB (configurable), validator limit 500MB
• Auth: JWT Bearer via IAM Service
• Framework: .NET 10.0, Clean Architecture + CQRS

---

API Endpoints

Files (/api/v1/files)

Method	Route	Auth	Description
POST	/api/v1/files/upload	Bearer	Upload a file (max 100MB)
GET	/api/v1/files	Bearer	List user files (skip, take, search)
GET	/api/v1/files/{fileId}	Bearer	Get file metadata by ID
GET	/api/v1/files/{fileId}/download-url	Bearer	Get pre-signed download URL
GET	/api/v1/files/{fileId}/cdn-url	Bearer	Get CDN URL (public) or fallback pre-signed URL
DELETE	/api/v1/files/{fileId}	Bearer	Soft delete a file

Direct Upload - Pre-Signed URL (/api/v1/storage)

Method	Route	Auth	Description
POST	/api/v1/storage/sign-upload	Bearer	Get pre-signed PUT URL for direct upload to MinIO
POST	/api/v1/storage/confirm-upload	Bearer	Confirm upload and save metadata after direct upload

Multipart Upload (/api/v1/files/multipart)

Method	Route	Auth	Description
POST	/api/v1/files/multipart/initiate	Bearer	Initiate multipart upload session
POST	/api/v1/files/multipart/upload-part	Bearer	Upload a single part (max 20MB per part)
POST	/api/v1/files/multipart/complete	Bearer	Complete and merge all parts
DELETE	/api/v1/files/multipart/abort	Bearer	Abort and cleanup
GET	/api/v1/files/multipart/{uploadId}	Bearer	Get upload progress

File Sharing (/api/v1/storage)

Method	Route	Auth	Description
POST	/api/v1/storage/files/{fileId}/shares	Bearer	Create share link (with optional password, expiry, max downloads)
GET	/api/v1/storage/files/{fileId}/shares	Bearer	Get all shares for a file
DELETE	/api/v1/storage/shares/{shareId}	Bearer	Revoke a share link
GET	/api/v1/storage/shares/public/{token}	Anonymous	Access shared file by token (public endpoint)

File Versioning (/api/v1/storage/files/{fileId}/versions)

Method	Route	Auth	Description
GET	/api/v1/storage/files/{fileId}/versions	Bearer	Get all versions of a file
GET	/api/v1/storage/files/{fileId}/versions/{versionId}/download	Bearer	Get download URL for specific version
POST	/api/v1/storage/files/{fileId}/versions/{versionId}/restore	Bearer	Restore file to a specific version

Folders (/api/v1/storage/folders)

Method	Route	Auth	Description
POST	/api/v1/storage/folders	Bearer	Create folder (root or child)
GET	/api/v1/storage/folders	Bearer	List folders (root or children of parentId)
GET	/api/v1/storage/folders/{folderId}	Bearer	Get folder by ID
PUT	/api/v1/storage/folders/{folderId}	Bearer	Rename folder (O(1) operation)
DELETE	/api/v1/storage/folders/{folderId}	Bearer	Soft delete folder

Quota (/api/v1/quota)

Method	Route	Auth	Description
GET	/api/v1/quota	Bearer	Get current user's storage quota

Admin - Files (/api/v1/admin/files)

Method	Route	Auth	Description
GET	/api/v1/admin/files	Admin/SuperAdmin	Get all files with filtering and pagination
DELETE	/api/v1/admin/files/{fileId}	Admin/SuperAdmin	Delete file (bypasses ownership, requires reason)

Admin - Quotas (/api/v1/admin/quotas)

Method	Route	Auth	Description
GET	/api/v1/admin/quotas	Admin/SuperAdmin	Get all users' quotas with filtering
GET	/api/v1/admin/quotas/{userId}	Admin/SuperAdmin	Get quota for specific user
PUT	/api/v1/admin/quotas/{userId}	Admin/SuperAdmin	Update user quota limits

Admin - Shares (/api/v1/admin/shares)

Method	Route	Auth	Description
GET	/api/v1/admin/shares	Admin/SuperAdmin	Get all file shares with filtering
DELETE	/api/v1/admin/shares/{shareId}	Admin/SuperAdmin	Revoke share (requires reason)

Admin - Statistics (/api/v1/admin/statistics)

Method	Route	Auth	Description
GET	/api/v1/admin/statistics	Admin/SuperAdmin	Get aggregated storage statistics
GET	/api/v1/admin/statistics/users-near-limit	Admin/SuperAdmin	Get users with usage >= 80%

Health Checks

Method	Route	Auth	Description
GET	/health	None	Full health check (incl. PostgreSQL)
GET	/health/live	None	Liveness probe (app running)
GET	/health/ready	None	Readiness probe

---

Commands

UploadFileCommand

• Input: Stream FileStream, string FileName, string ContentType, long FileSizeBytes, string UserId, string? TenantId, FileAccessLevel AccessLevel
• Logic: Check file size limit -> Check user quota -> Generate object key ({accessLevel}/{userId}/{date}/{uniqueId}_{filename}) -> Upload to storage provider -> Save StorageFile entity -> Update quota -> SaveEntities
• Validator: FileName (required, max 255, no .. / \), ContentType (required, max 100), FileSizeBytes (> 0, <= 500MB), UserId (required, max 128), TenantId (max 128)
• Result: UploadFileResult(bool Success, Guid? FileId, string? ObjectKey, string? Error)

SignUploadCommand

• Input: string UserId, string FileName, string ContentType, long FileSizeBytes, FileAccessLevel AccessLevel, string? TenantId
• Logic: Validate file size -> Check user quota -> Generate object key -> Ensure bucket exists -> Generate pre-signed PUT URL
• Validator: Same rules as UploadFileCommand
• Result: SignUploadResult(bool Success, string? UploadUrl, string? ObjectKey, DateTime? ExpiresAt, string? Error)

ConfirmUploadCommand

• Input: string UserId, string ObjectKey, string FileName, string ContentType, long FileSizeBytes, FileAccessLevel AccessLevel, string? TenantId
• Logic: Validate object key ownership (userId in path) -> Verify file exists in storage -> Idempotency check (existing file by objectKey) -> Double-check quota -> Create StorageFile entity -> Update quota -> Invalidate caches
• Validator: UserId (required, max 128), ObjectKey (required, max 1024), FileName (required, max 255), ContentType (required, max 100), FileSizeBytes (> 0)
• Result: ConfirmUploadResult(bool Success, Guid? FileId, FileDto? Metadata, string? Error)

DeleteFileCommand

• Input: Guid FileId, string UserId
• Logic: Get file -> Check ownership -> Delete from storage provider (best-effort) -> Soft delete record -> Update quota -> Invalidate caches
• Validator: FileId (required), UserId (required, max 128)
• Result: DeleteFileResult(bool Success, string? Error)

CreateFileShareCommand

• Input: Guid FileId, string UserId, SharePermission Permission, string? SharedWith, string? Password, DateTime? ExpiresAt, int? MaxDownloads
• Logic: Verify file exists + ownership -> Create FileShare entity (generates random token, hashes password with PBKDF2) -> Save -> Return share URL
• Validator: FileId (required), UserId (required, max 128), SharedWith (max 256), Password (min 4, max 100), MaxDownloads (> 0, <= 10000), ExpiresAt (must be future)
• Result: CreateFileShareResult(bool Success, Guid? ShareId, string? ShareToken, string? ShareUrl, string? Error)

RevokeFileShareCommand

• Input: Guid ShareId, string UserId
• Logic: Get share -> Verify ownership -> Revoke (idempotent) -> Save
• Result: RevokeFileShareResult(bool Success, string? Error)

InitiateMultipartUploadCommand

• Input: string FileName, long FileSizeBytes, string ContentType, string UserId, int? ChunkSizeBytes, FileAccessLevel AccessLevel, string? TenantId
• Logic: Validate file size -> Check quota -> Determine chunk size (default 5MB, min 5MB, max 100MB) -> Generate object key -> Initiate multipart upload at provider -> Create MultipartUpload entity (expiration: 24h) -> Save
• Result: InitiateMultipartUploadResult(... UploadId, ProviderUploadId, ObjectKey, BucketName, TotalChunks, ChunkSizeBytes, ExpiresAt ...)

UploadPartCommand

• Input: Guid UploadId, int PartNumber, Stream DataStream, string UserId
• Logic: Get upload with parts -> Verify ownership -> Check status (InProgress) -> Check expiration -> Upload part to provider -> Add part to domain entity -> Save
• Result: UploadPartResult(bool Success, string? ETag, string? Error)

CompleteMultipartUploadCommand

• Input: Guid UploadId, string UserId
• Logic: Get upload with parts -> Verify ownership -> Domain validation (all parts uploaded) -> Complete at provider -> Create StorageFile entity -> Update quota -> Save
• Result: CompleteMultipartUploadResult(bool Success, Guid? FileId, string? ObjectKey, string? Error)

AbortMultipartUploadCommand

• Input: Guid UploadId, string UserId
• Logic: Get upload -> Verify ownership -> Abort at provider (best-effort) -> Mark as aborted in DB -> Save
• Result: AbortMultipartUploadResult(bool Success, string? Error)

AdminDeleteFileCommand

• Input: Guid FileId, string AdminUserId, string Reason
• Logic: Same as DeleteFileCommand but bypasses ownership check. Logs admin action with reason.
• Result: AdminDeleteFileResult(bool Success, string? DeletedFileName, string? FileOwnerUserId, string? Error)

AdminRevokeShareCommand

• Input: Guid ShareId, string AdminUserId, string Reason
• Logic: Get share -> Revoke -> Log admin action with reason -> Save
• Result: AdminRevokeShareResult(bool Success, Guid? FileId, string? ShareOwnerUserId, string? Error)

UpdateUserQuotaCommand

• Input: string TargetUserId, long MaxStorageBytes, int MaxFileCount, string? QuotaTier
• Logic: Get or create quota -> Update limits (validates max >= current usage) -> Invalidate cache -> Save
• Validator: TargetUserId (required, max 128), MaxStorageBytes (> 0), MaxFileCount (> 0), QuotaTier (max 50)
• Result: UpdateUserQuotaResult(bool Success, QuotaUpdatedDto? Data, string? Error)

---

Queries

GetFileQuery

• Input: Guid FileId, string UserId
• Logic: Cache-aside pattern (10min TTL) -> Get from DB -> Check ownership
• Result: FileDto?

GetUserFilesQuery

• Input: string UserId, int Skip, int Take, string? SearchTerm
• Logic: If search term: search by filename; otherwise: list by userId -> Count total -> Map to DTOs
• Result: UserFilesResult(IReadOnlyList<FileDto> Files, int TotalCount)

GetUserQuotaQuery

• Input: string UserId
• Logic: Cache-aside pattern (5min TTL) -> GetOrCreate quota -> Map to DTO
• Result: QuotaDto?

GetDownloadUrlQuery

• Input: Guid FileId, string UserId, int ExpirationSeconds
• Logic: Get file -> Check access (private files: owner only) -> Mark accessed -> Generate pre-signed download URL
• Result: DownloadUrlResult(bool Success, string? Url, int? ExpiresInSeconds, string? Error)

GetFileSharesQuery

• Input: Guid FileId, string UserId
• Logic: Verify file ownership -> Get all shares for file -> Map to DTOs
• Result: IEnumerable<FileShareDto>

AccessSharedFileQuery

• Input: string Token, string? Password
• Logic: Get share by token -> Validate (not expired/revoked/limit reached) -> Validate password (PBKDF2) -> Get file -> Generate pre-signed download URL -> Increment download count -> Save
• Result: SharedFileAccessResult(bool Success, string? DownloadUrl, string? FileName, ...)

GetMultipartUploadProgressQuery

• Input: Guid UploadId, string UserId
• Logic: Get upload with parts -> Verify ownership -> Calculate progress
• Result: MultipartUploadProgressResult?

AdminGetFilesQuery

• Input: int PageNumber, int PageSize, string? UserId, string? AccessLevel, string? ContentType, DateTime? UploadedAfter/Before, string? SortBy, bool Descending
• Logic: IgnoreQueryFilters (includes soft-deleted) -> Apply filters -> Sort -> Paginate
• Result: AdminFilesResult(IReadOnlyList<AdminFileDto> Items, int TotalCount, int PageNumber, int PageSize, int TotalPages)

GetAllUsersQuotaQuery

• Input: int PageNumber, int PageSize, string? QuotaTier, double? MinUsagePercentage, string? SortBy, bool Descending
• Logic: Filter by tier, min usage% -> Sort -> Paginate
• Result: AllUsersQuotaResult(IReadOnlyList<AdminQuotaDto> Items, ...)

GetStorageStatisticsQuery

• Input: (none)
• Logic: Aggregate stats: total users, total storage used/allocated, total files, avg usage%, users by tier, users near limit (>80%), users over limit (>=100%)
• Result: StorageStatisticsDto

AdminGetSharesQuery

• Input: int PageNumber, int PageSize, string? Status, string? SharedBy
• Logic: Filter by status, sharedBy -> Paginate -> Order by CreatedAt desc
• Result: AdminSharesResult(IReadOnlyList<AdminShareDto> Items, ...)

---

Domain Model

StorageFile (Aggregate Root)

• Table: storage_files
• Fields: Id, FileName, BucketName, ObjectKey, ContentType, FileSizeBytes, UserId, TenantId, Provider (enum->string), AccessLevel (enum->string), UploadedAt, LastAccessedAt, ExpiresAt, Checksum, IsDeleted, DeletedAt
• Behavior Methods: MarkAccessed(), UpdateAccessLevel(level), Delete() (soft), SetExpiration(dt), UpdateFromVersion(objectKey, size, contentType)
• Domain Events: FileUploadedDomainEvent (on create), FileDeletedDomainEvent (on delete)
• Query Filter: !IsDeleted (global)

UserStorageQuota (Aggregate Root)

• Table: user_storage_quotas
• Fields: Id, UserId, MaxStorageBytes (default 1GB), UsedStorageBytes, MaxFileCount (default 1000), CurrentFileCount, QuotaTier (default "free"), LastUpdatedAt, CreatedAt
• Computed: RemainingStorageBytes, RemainingFileCount, UsagePercentage
• Behavior Methods: CanUpload(size), AddUsage(size, count), RemoveUsage(size, count), UpdateLimits(max, maxFiles, tier), RecalculateUsage(totalBytes, totalFiles)
• Domain Events: UserQuotaUpdatedDomainEvent (on AddUsage/RemoveUsage)
• Validation: UpdateLimits throws if new max < current usage

FileShare (Aggregate Root)

• Table: file_shares
• Fields: Id, FileId (FK -> storage_files), SharedBy, SharedWith, Permission (enum->string), ShareToken (unique, 32 random bytes base64), PasswordHash (PBKDF2-SHA256, 100K iterations), ExpiresAt, MaxDownloads, DownloadCount, Status (enum->string), CreatedAt, RevokedAt
• Behavior Methods: IsValid() (checks status, expiry, download limit), ValidatePassword(pwd), IncrementDownloadCount(), Revoke()
• Enums: SharePermission (View=0, Download=1, Edit=2, Admin=3), FileShareStatus (Active=0, Expired=1, Revoked=2, LimitReached=3)

FileVersion (Entity)

• Table: file_versions
• Fields: Id, FileId (FK -> storage_files), VersionNumber, ObjectKey, SizeBytes, ContentType, Checksum, CreatedAt, CreatedBy, Comment, IsCurrent
• Behavior Methods: MarkAsCurrent(), UnmarkAsCurrent()

Folder (Aggregate Root)

• Table: folders
• Fields: Id, UserId, ParentId (FK self-referencing, restrict delete), Name, Path (materialized path e.g. /parent/child/), Level (0=root), CreatedAt, UpdatedAt, IsDeleted, DeletedAt
• Behavior Methods: CreateRoot(userId, name) (static), CreateChild(name), Rename(newName), MoveTo(newParent), Delete() (soft)
• Design Note: Folders are LOGICAL only. Storage uses flat UUID keys. Rename/move is O(1) -- database-only.
• Query Filter: !IsDeleted (global)

MultipartUpload (Aggregate Root)

• Table: multipart_uploads
• Fields: Id, UserId, FileName, TotalSizeBytes, ChunkSizeBytes, TotalChunks (computed), UploadedChunks, ProviderUploadId, BucketName, ObjectKey, ContentType, Status (enum->string), CreatedAt, CompletedAt, ExpiresAt
• Behavior Methods: AddPart(partNum, etag, size), Complete() (validates all parts uploaded), Abort(), MarkFailed(), IsExpired(), GetProgressPercentage()
• Domain Events: MultipartUploadInitiatedDomainEvent, MultipartUploadCompletedDomainEvent, MultipartUploadAbortedDomainEvent
• Child Entity: MultipartUploadPart (Id, MultipartUploadId, PartNumber, ETag, SizeBytes, UploadedAt)
• Enums: MultipartUploadStatus (InProgress=0, Completed=1, Aborted=2, Failed=3, Expired=4)

---

Database Schema

Table: storage_files

Column	Type	Constraints
id	uuid	PK
file_name	varchar(255)	NOT NULL
bucket_name	varchar(100)	NOT NULL
object_key	varchar(500)	NOT NULL, UNIQUE
content_type	varchar(100)	NOT NULL
file_size_bytes	bigint	NOT NULL
user_id	varchar(100)	NOT NULL
tenant_id	varchar(100)	nullable
provider	varchar (string enum)	NOT NULL
access_level	varchar (string enum)	NOT NULL
uploaded_at	timestamp	NOT NULL
last_accessed_at	timestamp	nullable
expires_at	timestamp	nullable
checksum	varchar(100)	nullable
is_deleted	boolean	NOT NULL, default false
deleted_at	timestamp	nullable

Indexes: object_key (unique), user_id, tenant_id, uploaded_at, is_deleted Query Filter: is_deleted = false

Table: user_storage_quotas

Column	Type	Constraints
id	uuid	PK
user_id	varchar(100)	NOT NULL, UNIQUE
max_storage_bytes	bigint	NOT NULL
used_storage_bytes	bigint	NOT NULL
max_file_count	int	NOT NULL
current_file_count	int	NOT NULL
quota_tier	varchar(50)	nullable
created_at	timestamp	NOT NULL
last_updated_at	timestamp	NOT NULL

Indexes: user_id (unique)

Table: file_shares

Column	Type	Constraints
id	uuid	PK
file_id	uuid	NOT NULL, FK -> storage_files (CASCADE)
shared_by	varchar(255)	NOT NULL
shared_with	varchar(255)	nullable
permission	varchar(50) (string enum)	NOT NULL
share_token	varchar(255)	NOT NULL, UNIQUE
password_hash	varchar(255)	nullable
expires_at	timestamp	nullable
max_downloads	int	nullable
download_count	int	NOT NULL, default 0
status	varchar(50) (string enum)	NOT NULL
created_at	timestamp	NOT NULL
revoked_at	timestamp	nullable

Indexes: file_id, share_token (unique), shared_with, shared_by

Table: file_versions

Column	Type	Constraints
id	uuid	PK
file_id	uuid	NOT NULL, FK -> storage_files (CASCADE)
version_number	int	NOT NULL
object_key	varchar(500)	NOT NULL
size_bytes	bigint	NOT NULL
content_type	varchar(100)	NOT NULL
checksum	varchar(100)	nullable
created_at	timestamp	NOT NULL
created_by	varchar(255)	NOT NULL
comment	varchar(500)	nullable
is_current	boolean	default false

Indexes: file_id, (file_id + version_number) unique, (file_id + is_current)

Table: folders

Column	Type	Constraints
id	uuid	PK
user_id	varchar(255)	NOT NULL
parent_id	uuid	nullable, FK self (RESTRICT)
name	varchar(255)	NOT NULL
path	varchar(1000)	NOT NULL
level	int	NOT NULL
created_at	timestamp	NOT NULL
updated_at	timestamp	NOT NULL
is_deleted	boolean	NOT NULL, default false
deleted_at	timestamp	nullable

Indexes: user_id, parent_id, (user_id + parent_id + name) unique filtered is_deleted = false, path Query Filter: is_deleted = false

Table: multipart_uploads

Column	Type	Constraints
id	uuid	PK
user_id	varchar(255)	NOT NULL
file_name	varchar(255)	NOT NULL
total_size_bytes	bigint	NOT NULL
chunk_size_bytes	int	NOT NULL
total_chunks	int	NOT NULL
uploaded_chunks	int	NOT NULL
upload_id	varchar(255)	NOT NULL (provider upload ID)
bucket_name	varchar(255)	NOT NULL
object_key	varchar(500)	NOT NULL
content_type	varchar(100)	NOT NULL
status	varchar(50) (string enum)	NOT NULL
created_at	timestamp	NOT NULL
completed_at	timestamp	nullable
expires_at	timestamp	NOT NULL

Indexes: (user_id + status), upload_id, created_at

Table: multipart_upload_parts

Column	Type	Constraints
id	uuid	PK
multipart_upload_id	uuid	NOT NULL, FK -> multipart_uploads (CASCADE)
part_number	int	NOT NULL
etag	varchar(255)	NOT NULL
size_bytes	bigint	NOT NULL
uploaded_at	timestamp	NOT NULL

Indexes: (multipart_upload_id + part_number) unique

Migrations

1. 20260112185402_InitialCreate - storage_files, user_storage_quotas
2. 20260113155939_AddMultipartUploadTables - multipart_uploads, multipart_upload_parts
3. 20260113170635_AddFileSharing - file_shares
4. 20260113171238_AddFileVersioning - file_versions
5. 20260113171612_AddFolders - folders

---

Dependencies

NuGet Packages

API Layer:

• MediatR 12.4.1
• FluentValidation 11.11.0
• Microsoft.AspNetCore.Authentication.JwtBearer 10.0.1
• Swashbuckle.AspNetCore 7.2.0
• Asp.Versioning.Mvc 8.1.0
• AspNetCore.HealthChecks.NpgSql 8.0.2
• AspNetCore.HealthChecks.Redis 8.0.1
• Hellang.Middleware.ProblemDetails 6.5.1
• Serilog.AspNetCore 8.0.3

Domain Layer:

• MediatR.Contracts 2.0.1

Infrastructure Layer:

• Microsoft.EntityFrameworkCore 10.0.0
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.0
• MediatR 12.4.1
• Dapper 2.1.35
• Polly 8.5.0
• StackExchange.Redis 2.8.16
• Minio 6.0.4
• AWSSDK.S3 3.7.400 (for low-level multipart upload)
• Aliyun.OSS.SDK.NetCore 2.14.1

External Services

• IAM Service (http://localhost:5001) - JWT token validation
• MinIO (167.114.174.113:9000) - Object storage backend
• Redis (167.114.174.113:6379) - Caching (quota, file metadata, user files)
• PostgreSQL (Neon) - Metadata persistence

---

Configuration

appsettings.json

Section	Key	Default	Description
ConnectionStrings	DefaultConnection	Neon PostgreSQL	Database connection
Storage	Provider	minio	Active provider (minio or aliyun)
Storage	DefaultBucket	goodgo	Default S3 bucket
Storage	PreSignedUrlExpirationSeconds	3600	Pre-signed URL TTL
Storage	MaxFileSizeBytes	104857600 (100MB)	Max upload size
Storage:MinIO	Endpoint	167.114.174.113:9000	MinIO endpoint
Storage:MinIO	AccessKey	minioadmin	MinIO access key
Storage:MinIO	UseSSL	false	SSL for MinIO
Storage:MinIO	Region	us-east-1	MinIO region
Storage:AliyunOSS	Endpoint	(empty)	Aliyun OSS endpoint
Redis	Host	167.114.174.113	Redis host
Redis	Port	6379	Redis port
Redis	Database	0	Redis database index
Jwt	Secret	goodgo-iam-service-secret-key-32chars!	JWT secret
Jwt	Issuer	goodgo-platform	JWT issuer
Jwt	AccessTokenExpiryMinutes	15	Token TTL
CDN	Enabled	false	CDN integration toggle
CDN	BaseUrl	(empty)	CDN base URL
IamService	BaseUrl	http://localhost:5001	IAM service URL
IamService	TimeoutSeconds	30	HTTP timeout

---

Architecture Notes

Upload Patterns

1. Server-Side Upload (POST /files/upload): File goes through the API, uploaded to MinIO by the handler. Simple but doesn't scale for millions of concurrent uploads.
2. Direct Client Upload (POST /storage/sign-upload + POST /storage/confirm-upload): Client gets pre-signed PUT URL, uploads directly to MinIO, then confirms. Bypasses backend for file transfer -- highly scalable.
3. Multipart Upload (POST /files/multipart/initiate -> upload parts -> POST /files/multipart/complete): For large files, uploaded in 5MB chunks. 24-hour expiration.

Caching Strategy

• File metadata: Redis cache-aside, 10min TTL
• User quota: Redis cache-aside, 5min TTL
• Cache invalidation on: file delete, upload confirm, quota update

Security

• All user-facing endpoints require JWT Bearer auth
• File ownership validation on all operations (except admin endpoints)
• Share passwords hashed with PBKDF2-SHA256 (100K iterations, 16-byte salt)
• Share tokens: 32 random bytes, base64url-encoded
• Admin endpoints require Admin or SuperAdmin role
• Object key ownership validation via path structure ({access}/{userId}/...)

Object Key Structure

{accessLevel}/{userId}/{yyyyMMdd}/{8-char-uuid}_{sanitized-filename}

• accessLevel: public, private, or shared
• File names sanitized (invalid chars removed, max 100 chars + extension)

MediatR Pipeline

LoggingBehavior -> ValidatorBehavior -> TransactionBehavior -> Handler

Resilience

• PostgreSQL: retry on failure (5 retries, 30s max delay)
• IAM HTTP client: Polly retry (3 retries, exponential backoff) + circuit breaker (5 failures, 30s break)
• Storage delete: best-effort (continues with soft delete even if provider delete fails)
• Multipart upload abort: best-effort provider cleanup

Tests

• Unit Tests: StorageFile, FileShare, Folder domain entity tests; UploadFileCommandHandler, DeleteFileCommandHandler, SignUploadCommandHandler, FileShareCommandHandler tests
• Functional Tests: FilesApi, FileSharingApi, SignedUrlApi tests with CustomWebApplicationFactory (InMemory DB)