Freebee Ads docs

Product docs

All diagrams

Every drawing from the end-to-end flow and the UI/UX plan, in reading order. Each one links back to the section that explains it.

9 sections

End-to-end flow

Ops can add and pair screens at any time; an ad only reaches the wall once it is approved and booked.

An ad is made, approved, booked, played on the wall and countedFour lanes, top to bottom in time. Highlighted boxes are the game itself, in the mall.ADVERTISEROPS (ADMIN)SCREEN: WALL + KIOSKSHOPPERSign upemail and passwordCreate an advideo, image or gameBook a screenscreen, date, hoursCampaign reportplays, watchers, costAdd a screenmall, zone, screenPair the wallenter the player codeApprove the adplay test, approveToday and metricsall screens, all adsWall plays loopcricket ad shows QRKiosk: enter coderoll dice, wall playsCamera countsplays and watchersScan the QR codename, face, get codeWin a prizecoupon on the phoneapproved
end-to-end flow · 4 lanes, 13 steps

In End-to-end flow › The flow

Booking flow

There is no bidding: every screen has a fixed rate per slot per day set by ops, and an hour window costs its share of the day.

A booking reserves slots the moment it is confirmed; the wall plays once the ad is approvedBuilt today. The two side boxes are where a tester will see a message instead of the next step.Pick an advideo, image or game ad; preview it firstPick a screen and the datesrate per slot per day is shown on the cardPick the hoursgrid of 30 or 60 min blocks, 10:00 to 22:00Window free?Taken by another brandwho holds it and the next free oneSee the price, confirmrate × slots × days × share of the dayBooked, payment pendingslots reserved now; ops marks it paidAd approved?Waiting for ad approvalslots stay held; ops approves within a dayScheduled on the wallplays in the loop inside the hour windowReport fills the next morningplays, watchers, scans, cost per playnoyesnot yetyesonce approvedpick again
booking flow · 7 steps, 2 decisions

In End-to-end flow › Booking flow

Bidding for busy windows

Today every window is first come, first served at the fixed rate, which is right for most screens and most days.

On a busy day a main-screen window goes to the highest bid above the floorProposed. Ops switch bidding on per screen and day; every other window stays first come, first served.Advertiser picks a windowmain screen, a day ops marked as busyBidding on for this day?Book at the fixed ratefirst come, first served, as todayPlace a bidfloor or more; a max auto-raises for youBidding closes48 hours before the window startsHighest bid?Not won, nothing chargedoffered the next free window or screenWinner pays the bida tie goes to the earlier bidScheduled on the wallthe ad must be approved by the closenoyesoutbidyes
bidding for busy windows · proposed

In End-to-end flow › Bidding for busy windows

When things fail

The rule behind all four rows: a number that was never measured shows as a dash or a labelled sample, never as zero, and a play that was never recorded is never billed.

Each failure is noticed, shown to both sides, and has a next stepBuilt today unless marked proposed. Read each row left to right.WHAT GOES WRONGHOW WE NOTICEADVERTISER SEESOPS SEESTHENScreen offpower, wifi or theplayer tab closedNo check-infor 10 minutes;plays stop arrivingLive right nowshows the screen as"Nothing playing"Today alert"2 screens offline"plus the health tabProposedWhatsApp to ops;missed plays creditedCamera offor blocked, or aface-only cameraPlays arrivewith no audiencecounts attachedSample numbersin the Audience bandwith a clear noteMetrics tabdashes for watcherson that screenProposedops alert after aday without countsRecords helda batch fails checks,e.g. clock driftHeld for reviewnever silentlyaccepted or droppedNothing yetplays count oncethe batch is releasedHealth tab"held for review"count per screenOps reviewsreleases or dropsthe batchWindow takentwo brands want thesame wall hourClash at confirmthe second bookingis refusedGrid shows holderand the next freewindowBookings calendarboth brands on theweek gridPick anotherwindow or day;nothing is charged
failures · 4 cases, who sees what

In End-to-end flow › When things fail

OTP and coupons

The one-time code is the only moment we ask a shopper for anything personal, and only because the coupon has to live somewhere they can find again.

A win becomes a coupon in the phone wallet after a one-time codeBuilt today, except the code delivery: in test mode the code is shown on screen; WhatsApp or SMS delivery is proposed.Win on the wallruns reach a prize band;a claim QR showsPhone opens the claimone-time link, shows theprize before sign-inEnter phone numberstored hashed and encrypted;never shown to advertisers6-digit code arrivesvalid a few minutes; 5 tries;rate-limited per hourType the codewrong code: "That codedidn't match, try again"Coupon in the wallettitle, code, expiry; allcoupons at /wShow at the counterthe shop types the codein the advertiser portalRedeemed oncea second use is refused;counted in the report
OTP and coupons · 8 steps

In End-to-end flow › OTP and coupons

AI in the flow

What AI would do for an advertiser: take a phone photo of a product and return a clean, upright, 9:16 image with the background removed; turn a 10 second video into a mock-up of how it looks on the wall; suggest three headlines from the brand name and the product.

AI sits between the upload and the human approval, and between a typed name and the wallGreen = built today. Blue = proposed. A person still approves every ad.AD IMAGES AND COPYNAMES SHOPPERS TYPE FOR THE WALLUploadvideo, image, logo,product shot, packsFormat checktype, size, length;plain refusal messageAI enhanceupscale, cut background,fit 9:16, fix low lightAI preview + copywall mock-up clip;3 headline suggestionsOur team approvesplay test, approve orreject with a reasonShopper typesa name on the phonepage, any scriptBlock listleet, look-alikes,Telugu, Hindi, EnglishAI checkslang, mixed script,brands, real peopleAllowed or blocked"Please use your realname, no foul language"On the wallname band, scorecard,never stored with a phone
AI in the flow · 2 lanes, built vs proposed

In End-to-end flow › AI in the flow

Native player

A browser tab works for a demo but fails in a mall: it needs someone to open it, it can be closed or navigated away, it cannot start on boot, it loses the camera permission after a reboot, and a wifi drop stops the loop.

One player app for Android, Windows and Mac: same engine, counts on the device, syncs when onlineProposed. Today the wall is a browser tab; the app wraps that same engine so nothing on the server changes.Player app on the screen's deviceAndroid box or TV, Windows mini PC, Mac mini; installs once, starts on bootKiosk shellfull screen, auto-start, watchdogPlayback enginetoday's web engine, embeddedLocal cacheads, footage, schedule on diskVision modulecamera to counts, on the deviceSync agentpairing, check-in, upload queueKiosk and phone linksame pages, same screen idOffline modekeeps playing; records waitSelf-updatenew engine pulled from the cloudFreebee cloudunchanged from todaySchedule and assetswhat to play, when, with whatPlay record + audiencebatches checked, then countedGame servercodes, dice rolls, prizesDashboardsadvertiser and ops, as todayrecords up, schedule down
native player · app on the device, cloud unchanged

In End-to-end flow › Native player instead of a browser

Rollout phases

Phases 1 and 2 shipped on 22 October 2026 (commit df692c4 on main, auto-deploying to Vercel): the sidebar shell, the soft canvas, the advertiser Home, the ops Today page, and the new Campaigns and Reports pages, verified in the browser at desktop and phone width.

Four build phases, each gated before the next startsPhase 1 shipped first because every later page sits inside its shell1 FoundationSidebar and header shellSoft palette tokensKpiCard, WidgetCardOld links keep redirectingboth portals render in shell2 Home pagesAdvertiser HomeOps Today with alertsKPI deltas vs last rangeSchedule timeline rowslogin lands on a home page3 Page redesignsCampaign report re-layoutApprovals boardBookings calendarCreatives grid, book railend-to-end test passes again4 Site and extrasLanding page rebuildReports and Billing pagesScreen sparklinesAI assistant, laterdeployed on Vercel
rollout · 4 phases, 4 gates

In UI/UX analysis and plan › Rollout

Diagrams · Docs