CloudAPI - Project Overview

Solution Structure

The solution (TELS.CloudAPI.sln) contains 10 projects organized in a layered architecture:

Application Projects

Project	Type	Framework	Description
TELS.CloudAPI.Api	ASP.NET Core Web API	.NET 8.0	Main REST API service with 34 endpoints across 11 controllers
TELS.CloudAPI.MQServices	Worker Service	.NET 8.0	RabbitMQ message consumer service (propensity-to-win scoring)
TELS.CloudAPI.DAL	Class Library	.NET 8.0	Multi-database data access layer (PostgreSQL, SQL Server, Databricks, FastAPI)
TELS.CloudAPI.Contracts	Class Library	.NET Standard 2.0	Shared DTOs and data contracts

Test Projects

Project	Type	Description
TELS.CloudAPI.Api.UnitTesting	Unit Tests	Controller and service tests
TELS.CloudAPI.DAL.UnitTesting	Unit Tests	Data access layer tests
TELS.CloudAPI.MQServices.UnitTesting	Unit Tests	Consumer handler tests
TELS.CloudAPI.IntegrationTesting	Integration Tests	Full-stack API + database tests

Database Migration Projects

Project	Type	Description
PostgresMigrator	Console App	FluentMigrator for PostgreSQL schema
SQLMigrator	Console App	FluentMigrator for SQL Server schema

Architecture

Layering Pattern

┌─────────────────────────────────────────────┐
│         API Controllers (11)                 │
│      Controllers/*.cs                        │
├─────────────────────────────────────────────┤
│          Services Layer                      │
│           Services/*.cs                      │
├─────────────────────────────────────────────┤
│     Data Access Layer (Multi-DB)             │
│      DAL/Postgres/PostgresDataContext.cs     │
│      DAL/Sql/SqlDataContext.cs               │
│      DAL/Databricks/DatabricksDataContext.cs │
│      DAL/FastAPI/FastAPIDataContext.cs       │
├─────────────────────────────────────────────┤
│          Data Stores                         │
│  PostgreSQL Aurora | SQL Server              │
│  Databricks | FastAPI ML Service             │
└─────────────────────────────────────────────┘

Data Access

Primary Database: PostgreSQL Aurora Serverless V2 (auto-scaling)
Legacy Database: SQL Server (SQL-TELS-E-TRAN)
Analytics: Databricks (ODBC connection, read-only)
ML Service: FastAPI (HTTP REST calls)
ORM: Entity Framework Core 8.0 for PostgreSQL, Dapper for SQL Server
Migrations: FluentMigrator for both PostgreSQL and SQL Server

Multi-Database Strategy

Database	Purpose	Access Pattern
PostgreSQL	Primary operational store	Read/Write via EF Core, blue-green partitioning for dispatch_list
SQL Server	Legacy system source	Read-only via Dapper stored procedures
Databricks	Analytics queries	Read-only via ODBC with retry policy
FastAPI	ML predictions	HTTP REST calls for propensity-to-win scoring

Message Queue Integration

Broker: RabbitMQ via MassTransit 8.3.1
Pattern: Pub/Sub with 1 consumer in MQServices
Queue: tels.mqservices.buildingservices.cloudapi
Consumer: TELSPropensityToWinConsumer - processes ML scoring requests
Publisher: API publishes FlushCacheRequest via BusProxy

Key Features

1. Dispatch List Management

Multi-format exports: Raw, daily dashboard, service provider view, customer view
Blue-green partitioning: Zero-downtime data sync from SQL Server
Cold storage cleanup: Automatic archival of old partition data
User preferences: Personalized dispatch list settings per user

2. Complex Priority Scoring

Multi-factor prioritization: Market metrics (win rates, spend patterns, district manager config)
Databricks integration: Real-time analytics queries for facility/chain/owner metrics
Normalization: Scores scaled to 0-100 range
Batch processing: Supports bulk recalculation

3. Propensity-to-Win Scoring

ML-driven predictions: FastAPI model inference
Async processing: Via RabbitMQ message queue
Backfill support: Historical data scoring
Version tracking: Multiple model versions supported

4. Note Checker

Content validation: Configurable phrase matching
Real-time scanning: Returns potential violations with matched patterns
Configuration management: Per-organization validation rules

5. Work Item Management

Cintas batch processing: Bulk ticket imports
Description history: Track internal notes and work completion updates
Contact-based queries: Work items by person ID with secondary contact support

6. Permits & Fulfillment

CRUD operations: Create, read, update, delete permits
Authorization checks: Fulfillment-level access control
Inactive filtering: Include/exclude inactive permits

API Surface

11 controllers exposing 34 REST endpoints under buildingservices/v1/.

Authentication & Authorization

Auth: JWT Bearer token validation
Personas: DirectSupplyPartner, ServiceProvider, Customer
Claims: PersonId, DisplayName, Account, Persona extracted from token
Authorization: Persona-based access control via base controller validation

Swagger Documentation

Local: http://localhost:7181/buildingservices/docs
Deployed: http://{env}services.tels.net/BuildingServices/docs/index.html

Key Technology Stack

Category	Technology
Runtime	.NET 8.0
Web Framework	ASP.NET Core 8.0
PostgreSQL ORM	Entity Framework Core 8.0.8
SQL Server ORM	Dapper 2.1.44
Databases	PostgreSQL Aurora V2, SQL Server, Databricks
Messaging	RabbitMQ + MassTransit 8.3.1
Migration	FluentMigrator 5.2.0
HTTP Clients	Polly 8.4.2 for resilience
Logging	NLog 5.3.12
Monitoring	New Relic APM
Auth	JWT Bearer (System.IdentityModel.Tokens.Jwt 8.1.2)
Testing	xUnit, Moq
Containerization	Docker (ARM64 optimized)
CI/CD	GitLab CI
Infrastructure	AWS ECS, Terraform
Secrets	HashiCorp Vault

Deployment

Docker Containers

TELS.CloudAPI.Api - 2 task instances per environment (HA)
TELS.CloudAPI.MQServices - 1 task instance per environment

CI/CD Pipeline (GitLab CI)

Build → Test → Push → Deploy
Multi-environment: DEV, QA, PROD, SANDBOX
Container versioning: 1.0.${CI_PIPELINE_ID}
Security scanning: Checkmarx SAST
ARM64 optimized builds

Infrastructure

AWS ECS (Fargate/EC2)
Application Load Balancer with health checks
PostgreSQL Aurora Serverless V2 (auto-scaling)
RabbitMQ broker
Terraform-managed infrastructure
Vault for secrets management

Resource Allocation

Environment	API Tasks	API Memory	API CPU	MQ Tasks	MQ Memory	MQ CPU
DEV/QA/PROD	2	4GB each	2 vCPU each	1	4GB	2 vCPU
Total per env	—	8GB	4 vCPU	—	4GB	2 vCPU

Monitoring

New Relic APM: Transaction tracing, error tracking
CloudWatch: CPU/Memory alarms at 50% threshold
Health Check: /buildingservices/v1/cloudapi/health
Referrer URL: http://services.tels.net/cloudapi

Configuration

Configuration is managed through environment variables and HashiCorp Vault:

Configuration Group	Key Variables
Database	`SQLDATABASE__ConnectionString`, `POSTGRESDATABASE__ConnectionString`, `POSTGRESDATABASE__ReadOnlyConnectionString`
External Services	`APP__AuthorizationServiceEndpoint`, `APP__CustomersServiceEndpoint`, `APP__WorkOrdersServiceEndpoint`, `APP__BusProxyServiceEndpoint`, `APP__PlatformServiceEndpoint`
Auth	`APP__SIGNING_KEY` (Base64 JWT key), `APP__HostAccountRefreshToken`
RabbitMQ	`RMQTELS__Host`, `RMQTELS__Username`, `RMQTELS__Password`, `RMQBUILDINGSERVICES__*`
Analytics	`DATABRICKS__ConnectionString`, `FASTAPI__BaseUrl`
Feature Flags	`EnableCloudApiForDailyDashboard`, `EnableCloudApiForServiceProviderDispatchList` (in SMART)
Sync	`APP__DispatchListSyncDelayInSeconds`, `APP__MinTimeBetweenSyncInSeconds`

Data Sync & Partitioning

Blue-Green Partition Strategy

dispatch_list_data uses list-based partitioning: dispatch_list_blue and dispatch_list_green
Purpose: Zero-downtime data updates from SQL Server
Current Write Table: Tracked in dispatch_list_sync_settings.current_write_table
Read Table: Switched atomically during sync via dispatch_list_get_read_table() function
Cold Storage: Old partition data automatically cleaned up after sync

Sync Flow

Source: SQL Server WorkOrders via stored procedures
Transform: Map to DTO format
Load: Insert into PostgreSQL inactive partition
Enrich: Add Complex Priority Score and Propensity-to-Win scores
Switch: Atomic partition flip via function call
Cleanup: Archive old partition data

External Integrations

Integration	Mechanism	Description
Auth Service	HTTP	JWT token validation and refresh
Customers Service	HTTP	Customer/facility data queries
Work Orders Service	HTTP	Work order data access
Building Services	HTTP	Self-reference for callbacks
Platform Service	HTTP	Platform-level operations
BusProxy	HTTP	Message publishing with 45s timeout
Databricks	ODBC	Analytics queries (complex priority metrics)
FastAPI	HTTP	ML model predictions (propensity-to-win)

Testing Strategy

Test Type	Project	Execution
Unit Tests	TELS.CloudAPI.Api.UnitTesting	Controller/service logic
Unit Tests	TELS.CloudAPI.DAL.UnitTesting	Data access layer
Unit Tests	TELS.CloudAPI.MQServices.UnitTesting	Consumer handlers
Integration Tests	TELS.CloudAPI.IntegrationTesting	Full API + DB (Docker or LocalNoImposters)
Deep Integration	External repo: `deepintegrationtests`	End-to-end scenarios

Local Development Scripts

LocalSetup.ps1 - Complete local environment setup
DBSetup.ps1 - Database initialization
LocalDockerSetup.ps1 - Build Docker images locally
RunDockerIntegrationTests.ps1 - Run integration tests in Docker

Business Logic Patterns

Retry Strategy (Polly)

PostgreSQL: Handles serialization failures, deadlock detection
Databricks: 3 retries with 3-second delays
HTTP Clients: Decorrelated jitter backoff
Base Delay: 2 seconds for PostgreSQL, 3 seconds for Databricks

Transaction Management

PostgreSQL: Scoped transactions (no nested support)
SQL Server: DbTransaction per operation
Isolation Level: ReadCommitted (default)

Caching Strategy

Memory cache: Raw dispatch list results
Cache flush: Via API endpoint or BusProxy message
Cache key: Machine name + cache domain

Key Files & Locations

API Layer: - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.Api/Controllers/ - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.Api/Startup.cs

Data Access: - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.DAL/Postgres/PostgresDataContext.cs - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.DAL/Sql/SqlDataContext.cs - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.DAL/Databricks/DatabricksDataContext.cs - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.DAL/FastAPI/FastAPIDataContext.cs

Message Queue: - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.MQServices/Consumers/PropensityToWinConsumer.cs - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.MQServices/Program.cs

Migrations: - /c/Users/markc/gitlab/BuildingServices/CloudAPI/PostgresMigrator/ - /c/Users/markc/gitlab/BuildingServices/CloudAPI/SQLMigrator/

Configuration: - /c/Users/markc/gitlab/BuildingServices/CloudAPI/TELS.CloudAPI.sln - /c/Users/markc/gitlab/BuildingServices/CloudAPI/README.md