Doohlabs Ad Server

What it proves

One placement, one creative, one clock

A physical DOOH screen shows the same thing to everyone standing in front of it. This ad server reproduces that on the web: at any given second a placement has exactly one correct creative, and every visitor loading the page during that second sees it. Page loads do not influence what is shown — they only reveal what is already scheduled.

That property is the whole point of the build. Everything else in the codebase exists to support it.

Provisioning

Where a placement comes from

The diagram above starts at GET /p/{placementId} and takes that identifier for granted. It has to come from somewhere, and for the demo build it came from a map written into the source: two identifiers, one customer, and a redeploy for every addition. That does not survive a second customer.

A placement is born in the CMS. When one is created there, the CMS calls the ad server once, handing over its own address, the external player the placement belongs to, credentials to read that CMS with, and optionally where a click should go when the booking on screen has no click URL of its own. It gets back an opaque identifier and the embed code to show the user.

Two identifiers, and why both exist

A placement carries two UUIDs, and they belong to different systems. The player id is the CMS’s: it is what bookings are made against, and what proof-of-play is reported against. The placement id is this server’s, minted at provisioning. One is the key; the other is part of what it unlocks.

The indirection is not ceremony. An embed code lives on a publisher’s page indefinitely, so putting the CMS’s own player id there would hard-wire a third party’s identifier into pages nobody here controls — and if the CMS ever re-keyed its players, every live banner would break at once. A placement id cannot be invalidated by anything happening inside the CMS. It also reveals nothing: a random UUID in a public URL tells a competitor reading page source neither the customer nor the CMS behind it.

And one placement is one player today. Because the embed code carries only the placement id, that can change — a placement resolving to several players, or a player serving several placements — without reissuing a single tag.

Worth being exact about what is hidden: the player id does appear inside the served document, because the impression pixel carries it so a delivery knows what to report against. It is an identifier, not a credential. What never leaves the server is the CMS address and the credential the placement id unlocks.

A third identifier lives only in the browser: a page-view id, minted once when the document loads and never stored anywhere. The first counted pixel on a page — sequence 0 — is the page view. Every pixel after it on the same page, sequence ≥ 1, is a refresh impression: the same visitor, the same page view, a later creative. Both are impressions in the count that reaches the CMS; the distinction is what lets a page view be reported separately from how many times it refreshed.

Three properties are doing the work here.

• The identifier is opaque and permanent. Embed codes are pasted into publisher pages and stay there indefinitely, so the identifier can never be recomputed or reissued. It is a random UUID rather than anything derived from the customer, because it travels in a public iframe URL where a readable name would leak who is running which campaign.
• Registering twice is safe. The same CMS and player always return the same identifier, so a retried call cannot mint a duplicate — and rotating a credential means calling again with the new one, which updates it in place while every live embed code keeps working.
• Credentials are encrypted before they are stored. The registry holds a sealed blob; the key lives in the environment, apart from the data it opens. Nothing reads a credential back out except the flush that needs it to reach that customer’s CMS.

The endpoint is authenticated, which is a deliberate departure from the reporting routes below. Those were opened on purpose because nothing reachable through them can inject data. This one creates records holding customer credentials, so the same argument does not carry — and with no secret configured it refuses to run rather than defaulting to open.

The decision

How two bookings share one placement

Each booked row carries a play_amount over a time window. Dividing one by the other gives a weight — and in the live CMS every row works out to exactly 72 plays per hour, whether its window is two hours or seventeen. Equal weights mean an equal share, so the two bookings alternate.

Each booking then cycles its own creatives independently, on its own turns.

Code map

What is in the repository

Every source file under src/ with more than a few lines, and the one file outside it. The engine is the only one that matters conceptually — the rest is scaffolding around it. Paths are relative to src/; the line counts are checked against the repository on every test run, so they are current rather than estimated.

Structure

What is tied to what

The scheduling logic has no idea it is inside a web framework, and no idea which hosting platform it is on. That is not a stylistic preference — it is what makes the platform choice reversible while the product is still young.

Reading order for someone new to the code: api/index.ts hands every request to the Hono app in src/index.ts, which mounts one file per route under src/routes/; the routes call into src/lib/, which has no framework imports; and tests/ mirrors both, one file per module, running the engine, the routes and the in-page loop entirely offline against an in-memory Upstash and a fixture CMS.

Status

Where it stands today

Phase 1 and the Phase 2 items are built and running in production. Every row below has been exercised against the real Doohlabs CMS rather than test data; the one not marked verified waits on a destination for its messages.

Reporting

Where an impression goes

Every counted view fires a pixel onto a shared queue in Upstash. The queue depth shows on the inspector immediately as awaiting delivery; the settled figures follow once a cron flush delivers the batch to the Doohlabs CMS — one request per placement, holding anything the CMS has not yet accepted.

Deliberately absent

What it does not do yet

These are recorded rather than overlooked. Building them now would have added things that can break during a demo while proving nothing extra.

• No versioned delivery yet. Creatives are fetched from the CMS, held in memory, and cached at Vercel’s edge, both for the same configurable interval (an hour in production); a creative replaced in the CMS under the same id is live within two intervals, worst case, and the interval is a setting rather than a deploy. Versioned, year-long-cacheable URLs would let the edge hold bytes indefinitely; they are the upgrade if traffic ever makes the re-reads matter. The live creatives run from 506 KB to 2.7 MB — against a typical web banner budget of 150–200 KB, which is a strong argument for resizing them on ingest.
• No click reporting to the CMS. A click is counted here and redirected to the booking’s click URL from the CMS, or to the placement’s own link when the booking has none, and shows on the reporting page as a count and a click-through rate. The CMS has no endpoint to receive clicks yet, so that is where it stops: when one lands, the count travels with proof-of-play. The tag does not change.
• No user-initiated refresh. The ad runs in an iframe on the ad server’s origin, and a cross-origin iframe cannot see the publisher’s page — a reader scrolling or clicking the article is invisible to it. Refreshing on those signals, as some publishers do, needs a small script on the publisher’s side that tells the iframe; it is deferred until a customer asks for it. What the iframe can see is its own visibility, which is what the refresh floor and the one-second rule are built on.