Sovereign Transformers: Beyond the SQL Noise

“Code is not just logic; it is a contract of truth. When infrastructure leaks into your application layer, the truth becomes noisy.”

1. The Mess (The Diagnostic)

In the early stages of our BOS Era v2.0 migration, we faced a classic engineering sin: the God-Service. Our RadarSnapshotService was “functional” but architecturally loud.

It was directly injecting PDO, executing raw SQL queries, and handling UI formatting—all in a single file.

// The Original Mess (Contexts/Hub/Application/RadarSnapshotService.php)
public function getSnapshot(string $merchantId): array {
    $stmt = $this->pdo->prepare("SELECT SUM(total_amount) FROM finance_sales_tickets WHERE...");
    // ... raw query noise ...
    $liveRevenue = (float) $stmt->fetchColumn();
    
    return [
        'business_pulse' => [
            'live_revenue' => $liveRevenue,
            'occupancy_rate' => round(($confirmed / ($active * 8)) * 100) . '%', // UI Logic leaking!
        ]
    ];
}

Why this was Debt:

• Infrastructure Leaking: The service knew too much about table names and SQL syntax.
• Data Leaking: Returning raw associative arrays from PDO is a security vulnerability (Anti-Leaking failure).
• Location Blindness: Formatting dates without considering the Merchant’s local offset (emitting UTC ‘Z’ by default).

---

2. The Strategy (The Vision)

We defined ADR-006, establishing a strict separation of concerns through two specialized components:

1. The DataProvider: A silent infrastructure agent. Its only job is to fetch raw data. No logic, no formatting. Just the raw pulse of the database.
2. The Sovereign Transformer: A strict customs officer. It acts as a mandatory whitelist, ensuring only authorized fields leave the API, and enforcing Location Awareness (RFC3339 with dynamic offsets).

The Service then becomes a Pure Orchestrator. It asks for data, passes it through the transformer, and delivers the result.

---

3. The Craft (The Transformation)

Following our TDD Protocol, we first secured the “Green State” with an integration test suite. Then, we performed the surgery.

The New Infrastructure Layer

We abstracted the SQL into a dedicated RadarDataProvider.

class RadarDataProvider {
    public function getLiveRevenue(string $merchantId, string $start, string $end): float {
        // SQL stays here, hidden from the application logic.
    }
}

The Sovereign Contract

We implemented the RadarSnapshotTransformer, inheriting from our BaseTransformer. This guarantees that every date emitted follows the Merchant’s local time, not a generic UTC string.

class RadarSnapshotTransformer extends BaseTransformer {
    public function transform(array $data): array {
        return [
            'business_pulse' => [
                'live_revenue' => (float) $data['live_revenue'],
                'occupancy_rate' => $this->calculateOccupancy($data),
                // Location Awareness enforced here
            ]
        ];
    }
}

---

4. The Result (The Art)

The result is a service that reads like a story, not a database dump.

// The Refactored Orchestrator
public function getSnapshot(string $merchantId): array {
    $timezone = $this->dataProvider->getMerchantTimezone($merchantId);
    [$start, $end] = $this->getTodayRange($timezone);

    $data = [
        'live_revenue' => $this->dataProvider->getLiveRevenue($merchantId, $start, $end),
        // ... orchestration logic ...
    ];

    return $this->radarTransformer->transform($data);
}

The Evidence:

• 0 Lines of SQL in the application service.
• Strict Whitelisting (Safe from Data Leaking).
• 100% Location Awareness (Dynamic RFC3339 offsets).
• 17 Assertions Passing in our integration suite.

This is not just refactoring; it’s Engineering Sovereignty.

---

dammgo labs - Engineering as Art.