TELS Compliance Service - Project Overview

Solution Structure

The solution (TELS.Compliance.sln) contains 8 projects:

Application Projects

Project	Type	Framework	Description
TELS.Compliance.Api	Web API	.NET 8.0	REST API for approval workflows — articles, rules, roles, steps, notifications
TELS.Compliance.MQServices	Console App	.NET 8.0	RabbitMQ subscriber for workflow events — 10 consumers across 3 exchanges
TELS.Compliance.Contracts	Library	.NET Standard 2.0	Shared event and data contracts (published as NuGet, signed assembly)
TELS.Compliance.PostgresDbUp	Console App	.NET 8.0	DbUp database migration tool for PostgreSQL
TELS.Compliance.PostgresDbUp.LocalSetup	Console App	.NET 8.0	Local database setup utility

Test Projects

Project	Type	Description
TELS.Compliance.Api.Testing	NUnit (.NET 8.0)	API unit tests
TELS.Compliance.MQServices.Testing	NUnit (.NET 8.0)	Subscriber unit tests
TELS.Compliance.Testing.Integration	NUnit (.NET 8.0)	Integration tests (Mountebank)

---

Architecture

Purpose

TELS Compliance is a configurable approval workflow engine for the TELS ecosystem. It enables organizations (chains) to define rules that trigger multi-step approval workflows for various business events (service requests, quotes, fulfillments). The service provides:

1. Articles — Workflow instances that track an approval process from creation through authorization, denial, or expiration. Each article has dynamic attributes evaluated against rules to determine the required approval steps.

2. Rules Engine — Configurable per-client rules with article constraints (criteria) and step templates (workflow definitions). When an article is created, matching rules determine the approval workflow.

3. Roles & Assignments — Hierarchical approval roles (e.g., First Approver, Second Approver) with person assignments. Roles determine who can authorize each step in a workflow.

4. Steps — Individual approval actions within a workflow. Steps can be authorized, denied, expired (timeout), or bypassed. Steps support verbal authorization and auto-approval when the requester is in the approving role.

5. Notifications — Multi-channel notifications (email, SMS, push) for step actions. Includes A/B testing for email variants and configurable per-person notification preferences.

Layering Pattern

+-----------------------------------------------------+
|  API (TELS.Compliance.Api)                           |
|  ArticlesController — workflow instance management    |
|  RulesController — approval rule configuration        |
|  RolesController — role and assignment management     |
|  ClientsController — client/chain configuration       |
|  NotificationsController — notification preferences   |
|  ApprovalObjectTypesController — type lookups         |
|  DiagnosticController — health and debug              |
+-----------------------------------------------------+
|  Shared Contracts (TELS.Compliance.Contracts)         |
|  Event interfaces, data contracts, requests           |
+-----------------------------------------------------+
|  Subscriber (TELS.Compliance.MQServices)              |
|  10 consumers across 3 RabbitMQ exchanges             |
+-----------------------------------------------------+
|  DAL (DataBridge pattern + Dapper + Npgsql)           |
|  PostgreSQL (68 stored procedures)                    |
+-----------------------------------------------------+

Data Access

• PostgreSQL: Npgsql 6.0.11 + Dapper 2.1.66 — Stored procedure-based access via DataBridge pattern
• Retry Logic: Polly with 3 retries (1s, 2s, 3s) for transient PostgreSQL errors
• JSONB: Dynamic attributes, rules, and step templates stored as JSONB
• Migrations: DbUp with 50+ schema scripts (2020-2026), 68 stored procedures

Message Queue Integration

• Broker: RabbitMQ via MassTransit 5.5.6
• Exchanges: 3 (Compliance, WorkOrder, TELS)
• Consumers: 10 event consumers
• Published Events: 10+ event types via BusProxy with S3 fallback

---

Key Features

1. Approval Workflow Engine

• Object Types: ServiceRequestCreated, ServiceRequestCompleted, QuoteRequest, FulfillmentCompleted, NotToExceedExtensionRequest
• Article Statuses: PendingAuthorization, Authorized, Denied, QuoteRequested, NoRulesHit, PendingEvaluation
• Step Statuses: Pending Authorization, Authorized, Denied, Expired, Bypassed
• Dynamic Attributes: JSONB attribute dictionaries evaluated against configurable rules

2. Rules Engine

• Per-client (chain) rules with article constraints
• Constraint evaluation types: equals, greater_than, less_than
• Attribute types: Int, String, Decimal
• First matching rule's step templates copied to the article
• Step estimation API for previewing workflows before submission

3. Role Management

• Hierarchical roles with parent-child relationships
• Role assignments link people to roles
• History tracking for all assignment changes
• Auto-approval when requester is in the approving role
• Cascade evaluation on role user removal

4. Multi-Channel Notifications

• Email (AWS SES), SMS (Unity Notifications), Push (via Messaging Service)
• Per-person notification preferences with enable/disable per channel
• Email A/B testing with variant tracking (Original, A, B, C)
• Notification audit log (sent_notification table)
• URL shortening for SMS links

5. Step Timeout & Scheduling

• Configurable minutes-to-authorize per step
• Automatic timeout via scheduled IStepTimeoutV1 events
• Step pending approval notifications triggered via MQ

---

API Surface

7 controllers exposing 30+ endpoints:

Authentication

• JWT Bearer: Symmetric key signing
• Custom Authorization: Persona-based (DirectSupplyPartner, Customer, Resident), business unit access validation, role-based access
• Feature Flags: Some diagnostic endpoints gated by feature flags

See API Documentation for full endpoint details.

---

Key Technology Stack

Category	Technology
Runtime	.NET 8.0
Web Framework	ASP.NET Core 8.0, Asp.Versioning.Mvc 8.1.0
Data Access	Dapper 2.1.66 + Npgsql 6.0.11 (PostgreSQL)
Database	PostgreSQL (AWS RDS)
Messaging	RabbitMQ + MassTransit 5.5.6
Email	AWS SES
SMS	Unity Notifications (outbound SMS proxy)
Push	Messaging Service (push notification addresses)
Auth	JWT Bearer, TELS.WebServices.Auth.Contracts 4.1.1
Platform Settings	TELS.Platform.ClientSdk 1.2.0
Resilience	Polly 8.6.3 (3 retries, exponential backoff)
API Docs	Swashbuckle 6.4.0 (at /compliance/documentation)
Monitoring	New Relic 10.44.1, NLog 6.0.4
Bus Fallback	TELS.BusProxy.Client 3.0.1 (S3 + SQL fallback)
Testing	NUnit 3.13.3, Moq 4.18.2, Mountebank

---

Deployment

Docker Containers

• TELS.Compliance.Api — API (port 7160 locally, port 80 in container)
• TELS.Compliance.MQServices — Subscriber (no exposed ports)

Environments

Environment	URL
Local	http://localhost:7160
DEV	Sandbox AWS ECS
QA	Testing AWS ECS
PROD	Production AWS ECS

CI/CD Pipeline

Stage	Jobs
Build	dotnet build, docker buildx (ARM64 API/subscriber, AMD64 DbUp)
Test	Unit tests + coverage, integration tests
Push	NuGet contracts to ProGet, docker push
Security	Checkmarx SAST, Aqua container scans, dependency scans
Deploy	Terraform — RDS, ECS, data lake, API, subscriber, DbUp per environment

Infrastructure

• Platform: AWS ECS Fargate (ARM64)
• Database: AWS RDS PostgreSQL (with cluster upgrade support)
• Secrets: HashiCorp Vault
• Monitoring: CloudWatch + NLog (JSON), New Relic APM
• IaC: Terraform (modules: api, subscriber, ecs, rds, data-lake)

---

External Integrations

Integration	Mechanism	Description
Auth Service	HTTP API	Token refresh for service-to-service auth
Customers Service	HTTP API + NuGet (TELS.WebServiceClients.Customers.V1)	Support phone numbers, contact settings
Platform Service	HTTP API + NuGet (TELS.Platform.ClientSdk)	Feature toggles and settings
Unity Notifications	HTTP API + NuGet (Unity.Notifications.Messaging)	SMS phone status, outbound SMS/email
Messaging Service	HTTP API + NuGet (TELS.WebServices.Messaging.Contracts)	Push notification addresses
URL Shortener	HTTP API	Shorten URLs for SMS notifications
Work Items Events	MQ + NuGet (TELS.WorkItems.Events)	New work items and status changes
Customers Events	MQ + NuGet (DSE.TELS.Customers.Events)	Contact changes
BuildingServices	NuGet (BuildingServices.Contracts)	Shared data contracts
BusProxy	HTTP API (NuGet client)	Event publishing with S3/SQL fallback

---

NuGet Packages Published

Package	Target	Published To
TELS.Compliance.Contracts	.NET Standard 2.0	ProGet

---

Notes

• MassTransit 5.5.6: Uses an older version of MassTransit than most TELS services (which use 7.x-8.x). This may affect consumer configuration patterns.
• PostgreSQL: Like Platform and Quoting, Compliance uses PostgreSQL instead of SQL Server. Three TELS services now confirmed on PostgreSQL.
• JSONB-driven workflow: Rules, step templates, and article attributes are all JSONB, making the workflow engine highly configurable without schema changes.
• Self-consuming events: Many published events (ArticleCreated, StepTimeout, StepPendingApproval, EvaluateStep) are consumed by the service itself to drive workflow progression.
• A/B email testing: The quote_email_variant_log table tracks email variant experiments, suggesting active optimization of notification effectiveness.
• URL shortening: SMS notifications use a URL shortener service to keep messages within SMS length limits.
• Three fallback modes: BusProxy supports S3 fallback (cloud) and SQL fallback (local/integration), plus the primary HTTP delivery.