TELS Files Service - Project Overview

Solution Structure

The solution (Files.sln) contains 7 projects:

Application Projects

Project	Type	Framework	Description
TELS.WebServices.Files	Web API	.NET 8.0	REST API for file upload, download, metadata management, and file group organization
TELS.MQServices.Files	Console App	.NET 8.0	RabbitMQ subscriber for business unit changes and task document events
TELS.Files.Contracts	Library	.NET Standard 2.0	Shared DTOs and contracts (published as NuGet to ProGet)
Files.DbUp	Console App	.NET 8.0	DbUp database migration tool for SQL Server schema management

Test Projects

Project	Type	Description
TELS.WebServices.Files.Testing	NUnit (.NET 8.0)	Web API unit tests
TELS.MQServices.Files.Testing	NUnit (.NET 8.0)	Subscriber unit tests
TELS.Files.IntegrationTests	NUnit (.NET 8.0)	End-to-end integration tests (Mountebank, RestSharp)

Architecture

Purpose

TELS Files is a centralized file management service for the TELS ecosystem. It provides:

File Storage — Upload and download files via a REST API. File content is stored externally through the Unity File Handler service; SQL Server stores only metadata (file name, size, content type, dates, checksums).
File Organization — Files can be grouped into FileGroups and linked to external entities through CompositeIdentifiers (domain/type/identifier references), enabling flexible cross-service file associations.
Event-Driven Updates — A dedicated subscriber service listens for business unit changes (from Customers) and task document creation events (from Tasks) to maintain file associations.

Layering Pattern

+-----------------------------------------------------+
|  API (TELS.WebServices.Files)                        |
|  FilesController — upload, download, metadata CRUD   |
|  FileGroupsController — file group management        |
+-----------------------------------------------------+
|  Shared Contracts (TELS.Files.Contracts)             |
|  FileMetadata, FileGroup, CompositeIdentifier,       |
|  Request/Response DTOs                               |
+-----------------------------------------------------+
|  Subscriber (TELS.MQServices.Files)                  |
|  BusinessUnitChangeConsumer — facility changes        |
|  TaskInstanceDocumentConsumer — task document events  |
+-----------------------------------------------------+
|  DAL (FilesDataProvider, FileGroupsDataProvider)      |
|  Dapper + SQL Server (TELS database, Files schema)   |
|  UnityFileHandlerProxy (external file storage)        |
+-----------------------------------------------------+

Data Access

SQL Server: Dapper 2.1.44 — File metadata, file groups, composite identifiers, external references
Unity File Handler: External HTTP service for actual file content storage (upload/download via proxy)
Migrations: DbUp via Files.DbUp project (29 schema migrations, 19 stored procedures)

Message Queue Integration

Broker: RabbitMQ via MassTransit 8.3.0
Consumers: 2 (BusinessUnitChangeConsumer, TaskInstanceDocumentConsumer)
Published Events: None — this service is a pure consumer

Key Features

1. File Upload/Download

Upload files with metadata via multipart form POST
File content sent to Unity File Handler (Base64-encoded HTTP POST)
SQL Server stores metadata only: file name, size, content type, checksum, upload timestamp
Download returns file stream from Unity File Handler
MaxRequestBodySize set to int.MaxValue for large file support

2. File Metadata Management

Full CRUD on file metadata (GET, PUT, PATCH, DELETE)
Soft delete pattern via usp_FileSoftDelete
Search with pagination (facility-scoped, filterable by file groups, date range, search term)
EnabledForDocumentation flag for document-eligible files
File date tracking separate from upload date

3. File Groups

Organize files into named groups, optionally scoped to a chain (ChainID)
Groups can be linked to external references via composite identifiers
Full CRUD operations on file groups

4. External References (Composite Identifiers)

Flexible linking system: files and file groups can reference external entities
Three-part key: Domain + Type + Identifier (e.g., "Tasks" / "WorkOrder" / "12345")
Enables cross-service file associations without tight coupling

5. Event Handling

Business Unit Changes: Responds to facility changes from Customers service to keep file associations current
Task Document Creation: Processes task instance document events from Tasks service

API Surface

2 controllers exposing 13 endpoints:

Authentication

JWT Bearer: Symmetric key signing (AUTH__SIGNING_KEY environment variable)
Custom Authorization: Persona-based access control (DirectSupplyPartner, Customer)
Facility Authorization: Per-request facility-level access validation

See API Documentation for full endpoint details.

Key Technology Stack

Category	Technology
Runtime	.NET 8.0
Web Framework	ASP.NET Core 8.0
Data Access	Dapper 2.1.44 (SQL Server)
Database	SQL Server (TELS database, Files schema)
Messaging	RabbitMQ + MassTransit 8.3.0
File Storage	Unity File Handler (external HTTP service)
Auth	JWT Bearer (symmetric key), Custom persona-based authorization
API Versioning	Asp.Versioning.Mvc.ApiExplorer 8.1.0
Resilience	Polly 8.4.2
API Docs	Swashbuckle 6.9.0
Monitoring	New Relic 10.33.0, NLog 5.3.4 (JSON to CloudWatch)
Bus Fallback	TELS.BusProxy.Client 2.2.0 (S3 fallback)
Testing	NUnit 4.2.2, Moq 4.20.72, Mountebank, Coverlet

Deployment

Docker Containers

TELS.WebServices.Files — API (port 7180 locally, port 80 in container)
TELS.MQServices.Files — Subscriber (no exposed ports)

Environments

Environment	Host
Local	http://localhost:7180
DEV	devservices.tels.net
QA	qaservices.tels.net
PROD	services.tels.net

CI/CD Pipeline

Stage	Jobs
Build	dotnet build, docker buildx (multi-arch: arm64, amd64 for API; arm64 for subscriber)
Test	Unit tests + coverage, CSharpier format check, Terraform format check, integration tests, security scans (Checkmarx, Aqua)
Push	Docker tag latest, NuGet contracts to ProGet (manual)
Deploy	Terraform per environment (dev, qa, prod) — dependencies, API, subscriber, DbUp

Infrastructure

Platform: AWS ECS (multi-arch: arm64/amd64)
Scaling: 1-2 instances (256 CPU, 512MB memory)
Secrets: HashiCorp Vault + Envconsul
Monitoring: CloudWatch + NLog (JSON), New Relic APM
IaC: Terraform (modules: api, subscriber, dependencies)

Configuration

Configuration Group	Key Variables
Auth	JWT Bearer signing key (`AUTH__SIGNING_KEY`)
Database	SQL Server connection (DataSource, UserId, Password)
Messaging	RabbitMQ host, virtual host, username, password (`TELS_MQ`)
Endpoints	Unity File Handler URL, Auth service URL, Customers service URL
BusProxy	BusProxy client config with S3 fallback
ECommerce	DSSI Customer API authentication (client: TELSFilesService)

External Integrations

Integration	Mechanism	Description
Unity File Handler	HTTP API	File content storage (upload/download)
Auth Service	HTTP API + JWT	Token validation, service-to-service auth
Customers Service	HTTP API + NuGet client	Customer/facility data access
Tasks Service	HTTP API + NuGet client	Task data access
DSSI Customer API	HTTP API (ECommerce v5)	Internal application authentication
BusProxy	HTTP API (NuGet client)	Event publishing with S3 fallback
RabbitMQ	MassTransit 8.3.0	Message consumption

NuGet Packages Published

Package	Target	Published To
TELS.Files.Contracts	.NET Standard 2.0	ProGet (dev/prod feeds)

Key Files & Locations

API: - src/TELS.WebServices.Files/Controllers/V1/ — 2 controllers (Files, FileGroups) - src/TELS.WebServices.Files/Startup.cs — Service configuration - src/TELS.WebServices.Files/DAL/ — Data providers (Dapper)

Subscriber: - src/TELS.MQServices.Files/Consumers/ — 2 consumers (BusinessUnitChange, TaskInstanceDocument) - src/TELS.MQServices.Files/Configuration/ — MassTransit setup

Contracts: - src/TELS.Files.Contracts/ — Shared DTOs and request/response models

Database: - src/Files.DbUp/Schema/ — 29 migration scripts (2016-2025) - src/Files.DbUp/StoredProcedures/ — 19 stored procedures

Notes

Metadata-only storage: SQL Server stores file metadata only. Actual file content is stored externally via the Unity File Handler service.
Composite identifiers: The flexible domain/type/identifier reference system allows any external service to associate files without schema changes.
No published events: Unlike most TELS services, Files is a pure consumer — it does not publish any events to the message bus.
DSSI authentication: The service authenticates to Unity File Handler using DSSI Customer API tokens (ECommerce v5 client).
Multi-arch builds: API builds for both arm64 and amd64; subscriber builds arm64 only.
MassTransit 8.3.0: Uses a newer version of MassTransit than many other TELS services (which use 7.3.1).