Skip to main content

The Big Picture

In the code tour you followed a request from a component to "the backend." Time to zoom all the way out and see what's actually back there — because the data on an operator's screen started its life on a mountain top, inside a camera, minutes or seconds before it reached the browser.

Watch the data travel​

The diagram below is live — pick a flow and step through it. Capture follows a frame from the camera into storage; Tile Poll / Live View follows it from storage to the screen; Command follows a pan instruction going the other way, from an operator's finger back to the hardware.

Press Play to watch the system run itself, or step through with Next — each step lights up the exact wire and components involved, and the story so far stays traced behind you.

Capture — fires the instant a write completes Tile Poll / Live View — on a clock, or pushed to one page Command — RBAC-checked, applied on the next wake
Control-plane call — metadata or a path, through the BFF Media-plane fetch — raw image bytes, straight from Front Door
Node inspector

Click any node in the diagram for the real class, table, or entity behind that box.

Three things to notice while you're stepping:

  1. The browser only ever talks to its own server. Every control-plane arrow from the UI lands on the BFF first — never on the .NET services directly. You met this rule on day one; here you can see it hold for the entire platform.
  2. Images take a shortcut. Raw image bytes are fetched straight from the CDN (the media-plane wires), not proxied through the BFF. Metadata is sensitive and goes through the guarded path; pixels are big and go through the fast one.
  3. Commands are round trips with a wait built in. A PTZ command doesn't move a motor instantly — it's applied on the camera's next wake. That's why camera control has a whole concurrency protocol around it.

Inside the frontend: the ignition sequence​

Within our slice of that diagram, one file wires everything together: app/layout.tsx, the composition root. Read it top-down like an ignition sequence — each provider makes the next one possible:

  1. SessionProvider — next-auth session; nothing below renders for an anonymous user
  2. QueryClientProvider — the TanStack Query cache every data hook shares
  3. ConfigProvider — runtime configuration
  4. ThemeProvider — MUI theme, picked from themeStore
  5. An App-Insights error boundary — crashes become telemetry, not blank screens
  6. AuthGuard — the enforcement point (full story in Authentication)
  7. The real UI — Navbar, InactivityTracker, page content, notification/PWA plumbing

When you're hunting for where some cross-cutting concern is initialized — telemetry, the service worker, the install prompt — this file is always the first place to look. And the top-level screen it ultimately renders is components/pages/TileViewPage: the root of everything the operator sees.

The four commitments​

Everything else in this app is detail on top of four architectural commitments, each of which gets its full treatment in a later chapter:

Two routers, on purpose. app/ renders every real screen; pages/api/ holds only the BFF routes. Not a half-finished migration — a deliberate split you shouldn't "fix."

All data through the BFF. Component → query hook → pages/api/ route → .NET backend. The bearer token lives server-side only. Every route gets validation, tracing, and error mapping for free via withApiHandler.

State split by kind. TanStack Query (queries/) caches what the server says; Zustand (stores/) holds what the app knows. The whole state chapter is about the second half.

Design decided by tokens. Colors, spacing, and typography are generated from JSON token files — not hand-authored per component. MUI is deliberately confined to a handful of interactive primitives (Popover, Drawer, Dialog, Tooltip, Autocomplete, form inputs); layout and animation are hand-written SCSS against those tokens. The design-tokens lesson shows the pipeline.

Never hand-edit the generated files

Two code-generation pipelines run in this repo, and both produce files that look editable:

  • scripts/generateBackendSchemas.js (runs on predev/prebuild) writes lib/generated/backend-*.ts from the backend's OpenAPI spec. Import and .extend() these — never edit them.
  • npm run generate-design-tokens writes styles/_variables*.css and styles/variables*.js from the token JSON. Same rule.

Hand edits survive exactly until the next build, then vanish without a trace.

Wrapping up​

A frame travels mountain → capture services → storage → BFF → screen; a command travels the same road in reverse. Inside the frontend, app/layout.tsx boots the world in provider order, and four commitments — two routers, BFF-only data, state split by kind, token-driven design — shape every file you'll touch.

Next in this chapter: the design token system, or jump ahead to the features chapter to meet the map.