One Service Class per External System: An Integration Playbook

This is part 6 of the Musaned series. Parts 4 and 5 told the Oracle and MSSQL stories.

Oracle. MSSQL. LDAP. Third-party services. Internal company systems. Musaned's integration list grew past the point where I could keep the details in my head — which is exactly when architecture stops being a preference and starts being survival. This post is the playbook that emerged.

Rule 1: One service class per external system

Every external system Musaned talks to has exactly one home in the codebase: a dedicated service class that owns the connection details, the queries or API calls, the retries, and the mapping into Musaned's own data shapes. Nothing else in the application knows how to reach that system — not controllers, not Filament resources, not other services.

The payoff compounds with every integration:

• Debugging has an address. When fiber lookups misbehave, there is one file to open. Not a grep across the codebase.

• Credentials have one reader. Security reviews stop being archaeology.

• Change is contained. When a source system alters its schema or API, one class absorbs the hit.

• The ugly stays hidden. The Oracle service shells out to SQL*Plus internally; its callers just receive clean results. Aesthetics inside the boundary, contracts outside it.

Rule 2: Queues in a deliberate order

Integration work is bursty and heavy — a voucher sweep across 2M+ records, an LDAP full sync, a batch import. Run those on the same lane as everyday work and users feel it immediately: the innocent "approve this record" action queues behind a two-hour batch job.

So Musaned's queue topology is deliberately boring and strictly ordered: interactive and business-critical jobs live on their own high-priority queue; heavy batch and integration jobs live on separate queues that workers drain in a defined order. Batches are chunked so no single job monopolizes a worker for long, and the heavy lanes are scheduled with the business calendar in mind — the big sweeps run when they won't compete with humans. The result is the platform property users actually notice: Musaned never feels busy, even when it is.

Rule 3: Redis in front of repetition

Redis is Musaned's cache store, and its job description is one line: absorb repetition before it reaches systems we don't own. Frequent lookups from the MSSQL fiber store, reference data, expensive computed views — all cached with sensible lifetimes. Two disciplines keep this honest: every cache key has an owner (the service class that writes it also invalidates it), and cache lifetimes reflect how stale the business can tolerate data being, not how fast we can refresh it. A voucher status can be minutes old; an approval decision cannot.

The playbook in one paragraph

Automate the painful driver setup once. Give every external system one service class and make it the only door. Split queues by urgency and order them deliberately, chunk the heavy work, schedule it kindly. Cache repetition in Redis with owned keys and honest lifetimes. None of these ideas is novel — that's the point. Novelty is expensive at integration boundaries; predictability is what scales.

Next in the series: Voucher Query — the feature that turned 2M+ records into a self-service search for the business team.