RelatedOrderSync - Project Overview

Solution Structure

Solution: TELS.BuildingServices.RelatedOrderSync.sln

Project	Type	Framework	Description
TELS.BuildingServices.RelatedOrderSync	Console App (Worker Service)	.NET 8.0	Batch job for syncing related orders
TELS.BuildingServices.RelatedOrderSync.Tests	Unit Tests	.NET 8.0	Service tests

---

Purpose

RelatedOrderSync is a scheduled batch processing service that maintains comprehensive financial records for TBS (Building Services) tickets by linking related MDID orders.

Key Functionality

1. Sync MDID orders related to orders already linked to TBS tickets
2. Process Flow:
3. Claims processing targets by date
4. Queries eligible orders from MDID
5. Excludes already-linked or explicitly-unlinked orders
6. Finds related TBS tickets/PMT projects
7. Links new orders via Building Services API
8. Updates tracking tables
9. Data Relationships:
10. Links child orders to parent TBS tickets
11. Links PMT-project-linked orders
12. Safeguard: Never relinks orders explicitly unlinked by users

---

Architecture

Application Type

• Console Application running as a Generic Host (.NET 8)
• No API endpoints - batch job only
• No message queue integration
• Direct HTTP calls to Building Services API

Technology Stack

Category	Technology
Runtime	.NET 8.0
Data Access	Dapper 2.1.44 + Microsoft.Data.SqlClient 5.2.2
Database	SQL Server (TELS database)
HTTP Clients	TELS.WebServiceClients v4.5.2
Resilience	Polly 8.4.2 (exponential backoff, 3 retries)
Logging	NLog 5.3.14
Configuration	Microsoft.Extensions.Configuration
Hosting	Nomad (scheduled job)

---

External Dependencies

Building Services API

• Client: TELS.WebServiceClients.BuildingServices.V1 v4.50.0
• Purpose: Link orders to TBS tickets via API calls
• Authentication: JWT Bearer tokens via Auth Service

Auth Service

• Client: TELS.WebServiceClients.Auth.V1 v1.0.2
• Purpose: Token acquisition for service-to-service calls

Internal Contracts

• BuildingServices.Contracts v1.369.0 - Shared DTOs and models

---

Database Access

SQL Server (TELS Database)

Tables: - TELS.BuildingServices.RelatedOrderSyncProcessTargets - Tracks processing targets and dates - MDID Orders tables (queried for child orders, PMT-linked orders) - TBS ticket/order link tables (updated via API)

Pattern: Direct Dapper queries for read, HTTP API calls for write

---

Deployment

Execution Environment

• Platform: Nomad scheduler
• Runtime: Docker container
• Schedule: Configured in Nomad job definition
• Max Runtime: 3 hours per cycle
• Restart Policy: On-failure with delay

Configuration

• Database: SQL Server connection string
• API Endpoints: Building Services API URL
• Auth: Service account credentials
• Retry: Polly policy (3 retries, exponential backoff)

---

Key Processing Logic

1. Claim Processing Target

Query RelatedOrderSyncProcessTargets
  → Find next unprocessed date range
  → Mark as "claimed" (prevent concurrent processing)

2. Query Eligible Orders

Query MDID database
  → Find child orders of already-linked orders
  → Find orders linked to same PMT project
  → Exclude already-linked orders
  → Exclude explicitly-unlinked orders

3. Link Orders to TBS Tickets

For each eligible order:
  → Find related TBS ticket/project
  → Call Building Services API to create link
  → Handle errors (retry with Polly)
  → Update tracking table

4. Update Processing Target

Mark processing target as "completed"
  → Update timestamp
  → Log summary statistics

---

Configuration

Setting	Source	Description
Database Connection	Environment/Config	SQL Server connection string
Building Services API	TELS.WebServiceClients config	API base URL
Auth Service	TELS.WebServiceClients config	Auth service URL
Service Account	Environment	Credentials for API calls
Retry Policy	Code	3 retries, exponential backoff
Processing Batch Size	Config	Number of orders per batch

---

Monitoring & Logging

• NLog: Structured logging to console and files
• Log Levels: Info (normal flow), Warn (skipped orders), Error (failures)
• Metrics: Orders processed, links created, errors encountered
• Runtime Monitoring: Via Nomad job status

---

Key Files

File	Purpose
/src/Program.cs	Application entry point, host configuration
/src/Services/RelatedOrderSyncService.cs	Core sync logic
/src/Data/RelatedOrderSyncRepository.cs	Database queries (Dapper)
/src/Clients/BuildingServicesApiClient.cs	API client wrapper
/README.md	Service documentation
/nomad.yml	Nomad job definition
/Dockerfile	Container image definition

---

Notes

• No API: This is a background worker service only
• No Message Queue: Uses direct HTTP calls instead
• Safeguards: Respects explicit unlinking by users (never relinks)
• Idempotent: Can safely reprocess same date range
• Financial Accuracy: Ensures complete view of costs associated with TBS tickets