Build the Seam on Day One, the Second Driver on Day Ninety

I spent a long stretch this week building out the storage layer of an observability platform — the kind of system that ingests errors, metrics, and performance data from a lot of different applications and runtimes. By the end of the day I noticed something: I'd written nearly the same shape of code a dozen times, for a dozen different concerns. That repetition wasn't accidental. It was the architecture asserting itself. So this post is about that shape — the store seam — why it shows up everywhere in a platform like this, and the discipline that makes it pay off instead of just being ceremony.

I'm keeping everything here generic on purpose; the patterns are the point, not any particular product.

The problem: you don't know your storage yet, but you need to ship

When you start a platform that captures high-volume telemetry, you face a fork. The "correct" long-term answer for, say, error occurrences or web-vitals samples is probably a columnar or time-series store — something built for append-heavy, time-bucketed reads. But standing that up on day one is a huge yak-shave, and you're not even sure of your access patterns yet. The boring, reliable answer is a relational database you already operate well.

The wrong move is to pick one and scatter its assumptions through your whole codebase. If every dashboard query and every ingest path calls Eloquent directly, then "move occurrences to a columnar store" becomes a multi-week refactor touching hundreds of call sites. You've welded the platform to its first storage decision.

The right move is to decide where the seam goes before you decide what's behind it.

The shape: a contract plus a driver

For each storage concern, there's a small contract that describes what must happen, and one or more drivers that decide how. A contract is like a job description — it says what the role must accomplish, not which person fills it.

interface OccurrenceStore
{
    public function record(Occurrence $occurrence): void;

    /** @return iterable<OccurrenceBucket> */
    public function eventsOverTime(array $projectIds, TimeRange $range): iterable;
}

The first driver is the boring one:

final class EloquentOccurrenceStore implements OccurrenceStore
{
    public function record(Occurrence $occurrence): void
    {
        OccurrenceModel::create($occurrence->toAttributes());
    }

    public function eventsOverTime(array $projectIds, TimeRange $range): iterable
    {
        return OccurrenceModel::query()
            ->whereIn('project_id', $projectIds)
            ->whereBetween('occurred_at', $range->toBounds())
            ->selectRaw("date_trunc('hour', occurred_at) as bucket, count(*) as total")
            ->groupBy('bucket')
            ->orderBy('bucket')
            ->cursor();
    }
}

Bind it in a service provider:

$this->app->bind(OccurrenceStore::class, EloquentOccurrenceStore::class);

And — this is the whole point — every caller talks only to OccurrenceStore. The analytics page, the ingest pipeline, the trend chart. None of them import the model. None of them know it's Postgres.

The day the write volume justifies a columnar store, the work is: write ColumnarOccurrenceStore implements OccurrenceStore, change one bind() line, ship. No dashboard changes. No ingest changes. The contract was the promise; you're just swapping which class keeps it.

I did this same dance for occurrences, metrics, APM transactions, RUM samples, billing, and even tenant-connection resolution. Different domains, identical instinct: name the seam, write the boring driver, bind it, move on.

Why this beats "just add it later"

The objection I always hear: YAGNI — you only have one storage backend, the interface is premature abstraction. I think that misreads the cost curve.

The seam costs you exactly one extra file today — the interface. That's it. You were going to write EloquentOccurrenceStore's logic anyway; putting it behind a contract is a few lines of implements and a bind.

Skipping the seam doesn't save you that file. It defers it — and the deferred version is far more expensive, because by then a hundred call sites reach into the model directly, and introducing the interface means touching all of them under deadline pressure. You don't pay YAGNI's "you aren't gonna need it" tax here. You pay a one-file insurance premium against a refactor you very likely will need, in a domain where storage migration is a known eventuality, not a hypothetical.

The rule I'd give a junior: you don't need the second driver on day one — you need the interface on day one. The interface is what turns "rewrite everything" into "add one class."

The supporting cast

A few habits ran alongside the seams and made them sturdier.

Dual identifiers — internal vs. public. Every record carries an auto-increment internal id and a UUID public id. Joins and foreign keys use the fast integer; anything that crosses a boundary — a URL, an API response, the ingest envelope — uses the UUID. The internal id stays cheap; the public id never leaks how many rows you have or lets someone enumerate them.

Enums as the shared vocabulary. Roles, severities, statuses live in PHP enums with label() and color() helpers:

enum Severity: string
{
    case Fatal = 'fatal';
    case Error = 'error';
    case Warning = 'warning';
    case Info = 'info';

    public function label(): string
    {
        return ucfirst($this->value);
    }

    public function color(): string
    {
        return match ($this) {
            self::Fatal, self::Error => 'red',
            self::Warning => 'amber',
            self::Info => 'sky',
        };
    }
}

The authorization checks, the dashboard badges, and the ingest validation all read severity from the same enum. There's no magic 'fatal' string floating around three layers — change the vocabulary in one place and everything follows.

The envelope: one contract for many clients

The trickiest seam isn't internal — it's the wire. A platform like this is fed by SDKs in many languages. Each one captures an error or metric in its own runtime and sends it as a payload. If every client invents its own shape, the ingest pipeline becomes a swamp of special cases.

So the payload is pinned to a versioned envelope schema — a single shared contract that every client, in every language, serializes into. It has an explicit version field, and the ingest side routes on that version. The discipline that keeps this sane is additive-only evolution:

• Adding a new optional field → a minor bump (v1.0 → v1.1). Old clients keep working; they just don't send the new field. New servers tolerate its absence.
• Renaming or removing a field, or changing a type → a breaking change, and a new major version, handled by a separate code path.

A concrete example from this week: enriching the envelope so an error can carry its previous exception in the chain plus a few lines of source context around each stack frame. That's strictly new optional data — a v1.1 addition. An older SDK that doesn't send it still validates fine; the richer detail simply appears when a newer client provides it. No client was forced to upgrade in lockstep with the server.

One subtle serialization gotcha worth flagging: an empty context map has to encode as a JSON object {}, not an array []. In several dynamic languages an empty associative structure serializes to [] by default, which then fails a JSON-schema validator that expects an object. Each SDK had to force the object encoding for empty maps. It's the kind of cross-language papercut you only find by validating every client against the same schema — which is itself an argument for having one shared contract rather than per-client shapes.

The through-line

Whether it's storage (a Store contract with an Eloquent driver), identity (internal id vs. public UUID), vocabulary (enums with label()/color()), or the wire (a versioned, additive envelope) — it's all the same move: find the boundary, name it with a contract, fill it with the boring implementation, and keep the contract stable while implementations come and go.

The contract is cheap. The contract is the promise. The driver is just today's way of keeping it — and tomorrow you get to write a better one without anyone downstream noticing.