Architecture: Dispatch Modernization

The shape in one exec-readable paragraph, the decisions that made it (each a link, never restated rationale), and the tier declaration: this template covers the most complex case, and every chapter it scales down states the trigger value that justified it. Silence is never a tier.

A modular web system around one live board: a browser dispatch board, one backend API, a recommendation module behind a provider gateway, a telematics adapter, and a notification worker. Chosen over microservices for a five-hub scale (ADR-1^[7]). The shaping decisions: build the board and the recommendation core, reuse and buy the rest (ADR-2^[7], from the BRD options analysis^[3]); propose-only assignment posture (ADR-3^[7]); distance proxy over live traffic (ADR-4^[7]); one provider gateway for every model call (ADR-5^[7]).

Quality goals, ranked: board liveness · assignment integrity · feed-loss resilience; each carries a numeric scenario in §11. Deliberately not built: event sourcing beyond the assignment log, multi-region; the five-hub scale does not ask for them.

The system as one box with every user role and external system around it, generated from the committed model workspace, so this view and the container view can never drift apart. Every arrow states intent; the dependency index points each external system at its full contract in §8.

System context, generated from meridian.dsl (one Structurizr workspace produces every view), auto-laid-out, stamped 2026-07-16, commit-linked. Legend: teal round = person, teal box = the system, grey box = external system. Seven elements, within the ~9-element cap. Fallback: Dana and Priya dispatch via the board; Marcus works and confirms via mobile; telematics feed in, notifications out, legacy scheduler transitional.

Every container, its single responsibility, and what it owns that nothing else does. Overlap between containers is a finding, not a style. Component detail is earned, not defaulted; one container has it here. No code-level diagrams, ever: they rot.

The container view from the same model workspace as §2 (same source, no drift), plus one sequence per critical runtime flow. Not ten sequences: the two that carry the system's promises. Per-requirement behavior stays in the FRDs, referenced not restated.

Container view, generated from meridian.dsl, auto-laid-out, stamped 2026-07-16. Technology label on every box; every relationship states intent. Twelve elements, inside the 15-element hard ceiling; past it this view splits by domain, it does not shrink. Fallback: board ↔ API (authenticated calls); API → recommendation module (in-process, synchronous); adapter → API (normalized positions); API → store (events); worker ← store events → technician notifications.

Runtime view, critical flow 1: job to confirmed assignment

Sequence generated from committed source, stamped 2026-07-16. Solid arrows = synchronous calls; dashed = responses and async events. The closing note carries flow 2 in miniature: recommendation module down → the API serves the cached technician list and the board never blanks; full failure semantics in the FRD error catalog^[1].

Per container: language, framework, and the load-bearing dependencies with versions. Every non-obvious choice carries its decision link. AI capabilities are stated model-agnostically: the provider abstraction is the architecture; vendor names are configuration behind it.

Where every piece comes from: built from scratch, an extension of something that exists, a commercial product, an adopted open-source project, or another team's sub-system reused. The default order is reuse before buy, buy before build; a Build row must show what it evaluated and rejected. This table is the counter to reinventing what the company already has.

Who owns each entity, how data lives and dies, and the contracts on every exchange with more than one consumer. Engaged in full here because job ownership is contested until cutover; below roughly five shared entities and with no contest, this chapter is one table and says so. Physical schemas stay in the low-level design.

Conceptual entities: Job, Assignment, Technician, Position, ReasonCode: the business-readable model; the attributed logical model travels with the LLD.

System of record: one writer per entity

Lifecycle: create through purge, each transition with its authority

Data contract: the one multi-consumer exchange

Lineage. Positions: vendor feed → adapter (normalize, staleness flag) → API cache → board and recommendation inputs, an owner at every hop, so a contract violation's blast radius is traceable. The idle-time KPI reads from assignment events, not positions; measurement methodology lands with the BRD's success criteria^[3].

An integration is a contract, not an arrow. One full contract card for the load-bearing flow, the register for all three: protocol, auth, format, trigger, volume, expectations, owner, failure and retry semantics. A blank column is a decision not yet made and is flagged as such. Zero to two synchronous integrations would collapse this chapter to a paragraph; nothing integrates by shared database here.

Contract card: INT-1, the load-bearing flow

Register: all integrations

Engaged whenever an API is consumed outside the team that builds it. Here that is one consumer class (technician mobile clients on the public internet), so the chapter runs in collapsed form under its full heading: catalog, versioning promise, gateway shape. Partner webhooks at cutover re-engage it in full.

Versioning promise: path-versioned; a deprecated version lives 180 days with announce → migrate → remove dates published to the field-tools team (ADR-11^[7]). Gateway: external mobile traffic enters through the managed edge; in-process calls stay internal; no per-client shaping yet (one client class).

Re-engagement note: partner webhooks land at cutover, and this chapter then runs in full: per-partner registration, rate limits (§17), and the external consumer register.

The index, not the decisions: every record referenced anywhere in this document appears here, and every row resolves to its full record in the decision log^[7]. Superseded decisions stay listed with their successor; history is never rewritten.

Stimulus-response scenarios with numbers; an attribute without a numeric response measure is an aspiration, not architecture. Each scenario names the structural mechanism that satisfies it and the requirement it supports.

Scale frame: five hubs, 1,500 jobs/day, 400 technician positions/minute; first expected bottleneck at adapter fan-in (§13). Attributes deliberately not driving the shape: multi-region availability, sub-100-millisecond anything.

Where data enters, moves, is stored, and leaves, with every privacy boundary marked and the data class named at each crossing. Drawn at boundary altitude and consistent with §7's lineage; the model provider sits behind one gateway so every call inherits the same policy, guardrails, and audit trail.

Data flow with privacy boundaries, generated from committed source, stamped 2026-07-16. Legend: dashed amber = the residency zone; PB-1 feed ingress (location = personal data, Canada residency), PB-2 provider boundary (anonymized codes only). Cylinders are stores with their retention. Fallback: feed → adapter → cache → board; board → event log → worker → devices; cache → gateway → model provider, anonymized.

Obligations on the diagram: location data stays in Canada (enterprise contracts^[2]); retention matches §7's lifecycle: positions purged at 30 days, assignment history archived at 7 years.

The load shape in numbers, the first bottleneck beyond it, and what stays up when each load-bearing dependency is down. Caching lives here because caching is a scaling decision, not a separate discipline.

Built for: five hubs, 1,500 jobs/day, 400 positions/minute, with tenfold headroom at the API. First bottleneck: adapter fan-in beyond 2,000 positions/minute, the revisit trigger, tied to the hub-six question (§17). Caching: the technician list is cached client-side (the never-blank fallback) and positions are cached in the API for 60 seconds; invalidation is push-on-assignment-events. Degradation: per dependency, reconciled with the FRD error catalog^[1] and §8's failure columns: feed silent means proximity drops with flags, never blocked assignments; notification outage degrades to board-only confirmation.

Every quality scenario's measure has a signal that observes it; an unobserved scenario is untestable. One correlation id tells a job's whole story.

Correlation: an id minted at job intake carries through suggestion, assignment, and notification. Signals: suggestion latency distribution, feed staleness, assignment event lag, notification delivery rate, dead-letter depth per integration; §11's three measures each map to one. Paging: feed silent > 10 minutes pages the engineering lead; suggestion latency breach surfaces per the FRD threshold. Procedures live in the operations runbook^[4].

One table, pointer-first: where each container runs and what environments exist. Everything operational (deploy, rollback, credentials) lives in the runbook, linked never duplicated.

Each item with the trigger that makes it bite, an owner, and a revisit condition; none is a vague worry. Sourcing-borne exposures from §6 surface here. An empty risk section is omitted, never padded.

Owned and dated, with the decisions or containers each blocks; an unowned question is not tracked.

Omission note, how a scaled-down chapter renders on a simpler project: "§8 Integration Architecture (collapsed): this system has one synchronous integration (payments provider), contracted in the dependency index. Trigger: below the three-or-async threshold. Rationale recorded in adaptation event #3."

Package items travel in the same export bundle; workspace items link into Specira where the governed record lives.

In this export package

In the Specira workspace