TELS Platform Service - Project Overview

Solution Structure

The solution (TELS.Platform.Api.sln) contains 5 projects:

Application Projects

Project	Type	Framework	Description
TELS.Platform.Api	Web API	.NET 8.0	REST API for platform-level settings and configuration management
TELS.Platform.Contracts	Library	.NET Standard 2.0	Shared data/event/request/response contracts (published as NuGet v1.2.0)
TELS.Platform.ClientSdk	Library	.NET Standard 2.0	C# client SDK with typed proxies and Polly resilience (published as NuGet v1.2.0)
TELS.Platform.DbUp	Console App	.NET 8.0	DbUp database migration tool for PostgreSQL schema management (plan/apply)

Test Projects

Project	Type	Description
TELS.Platform.Api.Tests	xUnit (.NET 8.0)	API unit tests

Architecture

Purpose

TELS Platform is a centralized configuration and settings service for the TELS ecosystem. It provides:

Subsystem Settings — A generic key-value store where each setting is identified by a subsystem name + setting name pair. Values are stored as JSONB, allowing flexible schema-less configuration for any data type.
Client SDK — A published NuGet package (TELS.Platform.ClientSdk) that other TELS services use to read and write platform settings, with built-in Polly retry policies (5 retries, exponential backoff).
Audit Trail — All setting changes (create, update, delete) are automatically recorded in a history table with person, persona, and timestamp tracking.

Layering Pattern

+-----------------------------------------------------+
|  API (TELS.Platform.Api)                             |
|  SettingsController — settings CRUD by subsystem     |
|  DiagnosticsController — health check, DB status     |
+-----------------------------------------------------+
|  Shared Contracts (TELS.Platform.Contracts)          |
|  PlatformSetting<T>, ScheduledMessageEvent,          |
|  PutPlatformSettingRequest, PagedResponse             |
+-----------------------------------------------------+
|  Client SDK (TELS.Platform.ClientSdk)                |
|  ISettingsProxy — typed HTTP client with Polly       |
+-----------------------------------------------------+
|  DAL (Custom DataProvider + Npgsql)                  |
|  PostgreSQL (platform database, platform schema)     |
+-----------------------------------------------------+

Data Access

PostgreSQL 15.3: Npgsql 7.0.7 — Direct ADO.NET access via custom DataProvider pattern
No ORM: Does not use Entity Framework or Dapper — uses raw NpgsqlConnection with table-valued functions
Transactions: Repeatable Read isolation for write operations
IAM Auth: Optional AWS RDS IAM authentication for production
Migrations: DbUp with PostgreSQL support (plan/apply commands)

Message Queue Integration

None — The Platform Service does not use RabbitMQ or MassTransit. It is a pure REST API service.

Key Features

1. Subsystem Settings Management

Generic key-value configuration store: subsystem name + setting name → JSONB value
Full CRUD: read all, read by subsystem, read single, upsert, delete
JSONB storage enables any data type (strings, objects, arrays, numbers)
Cursor-based pagination with configurable page size (default 1000)
Case-insensitive lookups via lowercased index columns

2. Client SDK

Published as TELS.Platform.ClientSdk NuGet package
ISettingsProxy with typed generic methods: GetSubsystemSettingAsync<T>, PutSubsystemSettingValueAsync<T>
Built-in Polly retry policy: 5 retries with exponential backoff (max 5 seconds)
OrDefault variants that return null instead of throwing on missing settings
ProblemDetails-aware exception handling

3. Audit History

All setting modifications automatically recorded in platform.settings_history
Tracks: person ID, person name, persona, action type (insert/update/delete), timestamp
Implemented within PostgreSQL table-valued functions (tfn_setting_m, tfn_setting_d)

4. Event Contracts

ScheduledMessageEvent contract defined (SubsystemName, MessageName, Description, Schedule)
Consumed by other services (e.g., Customers Service ScheduledMessageConsumer)
Event publishing mechanism not in this repo — likely published by a separate scheduler

API Surface

2 controllers exposing 8 endpoints:

Authentication

JWT Bearer: Symmetric key with issuer/audience validation
Custom Authorization: Persona-based (DirectSupplyPartner for writes, DirectSupplyPartner | Customer | Owner for reads)
Health checks: Anonymous access

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	Npgsql 7.0.7 (PostgreSQL, raw ADO.NET)
Database	PostgreSQL 15.3 (platform database, platform schema)
Auth	JWT Bearer (symmetric key), custom persona authorization
API Docs	Swashbuckle 6.5.0 (at `/platform/swagger`)
Monitoring	New Relic APM
Resilience	Polly 7.0.9 (in ClientSdk)
Testing	xUnit 2.4.1, Moq 4.18.4

Deployment

Docker Containers

TELS.Platform.Api — API (port 7183 locally, port 80 in container)

Environments

Environment	URL
Local	http://localhost:7183
DEV	https://devservices.tels.net/platform
QA	https://qaservices.tels.net/platform
PROD	https://services.tels.net/platform

CI/CD Pipeline

Stage	Jobs
Build	dotnet format verify, dotnet build, xUnit tests, docker buildx (arm64/amd64), container security scan, terraform verify
Publish	NuGet push Contracts + ClientSdk to ProGet (manual)
Deploy	Terraform per environment (dev, qa, prod) — RDS reboot, DbUp plan/apply, API plan/apply

Infrastructure

Platform: AWS ECS Fargate (ARM64)
Database: AWS RDS PostgreSQL with IAM authentication
Resources: 512 CPU / 1024 MB memory, auto-scaling 1-4 tasks
Secrets: AWS Secrets Manager (JWT signing key, New Relic license)
Monitoring: CloudWatch Logs (3-day retention), New Relic APM with infrastructure sidecar
IaC: Terraform

Configuration

Configuration Group	Key Variables
Auth	JWT issuer signing key, issuer, audience
Database	PostgreSQL host, port, database, IAM auth toggle
Pages	Default page size (1000)

External Integrations

Integration	Mechanism	Description
AWS RDS PostgreSQL	Npgsql + IAM tokens	Database hosting with IAM authentication
AWS Secrets Manager	Terraform/ECS	JWT signing key, monitoring license

NuGet Packages Published

Package	Target	Published To
TELS.Platform.Contracts	.NET Standard 2.0	ProGet
TELS.Platform.ClientSdk	.NET Standard 2.0	ProGet

Key Files & Locations

API: - TELS.Platform.Api/Controllers/ — 2 controllers (Settings, Diagnostics) - TELS.Platform.Api/Program.cs — Service configuration - TELS.Platform.Api/Data/ — Data providers and context factory

Contracts: - TELS.Platform.Contracts/ — Shared data/event/request/response contracts

Client SDK: - TELS.Platform.ClientSdk/ — Typed HTTP proxies with Polly resilience

Database: - TELS.Platform.DbUp/Scripts/Tracked/Schema/ — Versioned migrations - TELS.Platform.DbUp/Scripts/Untracked/AfterSchema/ — Stored functions

Notes

PostgreSQL: This is the only documented TELS service using PostgreSQL instead of SQL Server. All other services use SQL Server with Dapper.
No messaging: Unlike most TELS services, Platform has no RabbitMQ/MassTransit integration. It is a pure REST API.
JSONB settings: The use of PostgreSQL JSONB for setting values provides maximum flexibility — consumers can store any JSON-serializable type as a setting value.
ScheduledMessageEvent: The contracts define a ScheduledMessageEvent that is consumed by other services (e.g., Customers), but the publishing mechanism is not in this repository.
Minimal dependencies: The service has no outbound HTTP calls to other services, making it a foundational leaf service in the dependency graph.
Client SDK resilience: The SDK's 5-retry exponential backoff policy makes it resilient to transient failures, important since multiple services depend on platform settings.