How the Demo Portal Works

1 The 10,000-ft view

A self-service portal where a Cloud Solution Architect types a customer name, and minutes later a tailored, interactive Copilot demo appears — researched, branded, and ready to show.

Three moving parts do all the work. The Portal is the web app you log into. The Worker is an autonomous agent that builds demos in the background. The Shared Storage is where finished demos live and get served to end users.

2 Stack & hosting

Everything runs serverless on Azure Container Apps — no VMs to patch, scales to zero, deploys as immutable container images.

3 The demo build pipeline

When a CSA hits "Build Demo," the work doesn't happen in the web request — it can't, it takes minutes. Instead the portal records the job and hands it off. This is asynchronous job processing.

Step by step

• Request — CSA submits the form. Portal generates a requestId, derives a URL-safe slug, and writes a row to demo_requests with status pending.
• Discover — The worker polls GET /api/pending and sees the new job.
• Claim — Worker calls POST /api/claim/:id. This atomically flips the row to processing (more on why that matters in §6).
• Build — Worker researches the customer (Bing + AI Search), generates tailored Copilot content, and renders the demo HTML.
• Persist — Finished demo folder (HTML + meta.json) is written to /data/demos/<slug>/ on shared storage.
• Report — Worker calls POST /api/callback/:id with status completed. The demo now appears in the gallery.

4 The autonomous worker

The worker is the secret sauce — a separate Azure Container App running an AI agent that wakes up every ~30 seconds, asks "any work for me?", and builds demos completely unattended.

It's a classic polling consumer. Rather than the portal pushing work (which breaks if the worker is asleep), the worker pulls work on its own schedule. This decouples the two: the portal can restart, the worker can restart, and nothing is lost — pending jobs just wait in the database until someone claims them.

// Worker's heartbeat loop (conceptual)
while (running) {
  const jobs = await fetch('/api/pending');   // what's waiting?
  for (const job of jobs) {
    const claimed = await claim(job.id);       // call dibs (atomic)
    await buildDemo(job);                     // the heavy lifting
    await callback(job.id, 'completed');    // report back
  }
  await sleep(30_000);                       // nap, repeat
}

5 The SMB database problem

Here's a war story. SQLite is brilliant — but it relies on byte-range file locks to coordinate writes. Azure Files (the SMB network share) doesn't honor those locks reliably. Result: SQLITE_BUSY crashes on the very first write.

We can't put the live database on the share. But we need data to survive deploys (containers are ephemeral — restart and local disk is wiped). The fix is a two-location dance:

• On boot — copy the persisted DB from the share into /tmp (local disk SQLite can actually lock).
• While running — all reads/writes hit the fast local copy. No SMB, no SQLITE_BUSY.
• To persist — use SQLite's online-backup (VACUUM INTO) to grab a consistent snapshot, then atomically rename it onto the share (a plain file copy SMB does allow).

6 The claim-race war

The nastiest bug we fought. For a window of time, two workers were alive — the real Azure worker, and a leftover "zombie" from an old environment. Both polled the same queue. Both tried to build the same demo. Chaos: duplicate demos, fake completions, corrupted state.

The fix is elegant and lives in the database, not the application logic. The claim is a single atomic SQL statement:

UPDATE demo_requests SET status = 'processing'
WHERE request_id = ? AND status = 'pending';

SQLite guarantees this runs atomically. Whichever worker's statement lands first changes one row (result.changes === 1) and earns the job. The second worker's identical statement matches zero rows — the status is no longer pending — so it gets changes === 0, the portal returns 409 Conflict, and that worker politely moves on.

7 Archive & lifecycle

Not every demo should be deleted. Some are old, some are one-off, but you might still want to hand a prospect a direct link. So demos have three states.

How archive works under the hood: it's just a flag. Archiving writes "archived": true into the demo's meta.json. The gallery endpoint filters those out (demos.filter(d => !d.archived)), but the static file server never checks the flag — so the folder's index.html keeps serving at its direct URL. Restore simply deletes the flag. Nothing moves, nothing is copied; one boolean controls visibility.

8 Security model

Two trust zones: humans log in with sessions; the worker authenticates with a shared secret. Every action is logged.

• Human auth — username + bcrypt-hashed password, server-side session cookie. Admin vs. viewer roles gate destructive actions (delete, archive, user management).
• Machine auth — the worker's endpoints (/api/pending, /api/claim, /api/callback) require a webhook secret, not a session. No browser, no cookie needed.
• Audit trail — logins, demo views, deletes, archives — all written to an access_logs table with user, IP, and timestamp.
• Path-traversal guards — slugs are rejected if they contain .. or /, so a crafted request can never escape /data/demos.
• Secrets — API keys and connection strings live in Container App environment variables, never in the image or the code.