Worker Portal Redesign — Stage 5 MR1: Composition-driven worker dashboard

ADR-021 requires per-export slugs distinct from the plugin slug. Plugin slugs use worker-dashboard-{name}; the single panel each plugin exports uses worker-dashboard-{name}-panel. Composition references the panel export slug. The dispatcher matches on the panel export slug (not the plugin slug).

All slugs match ADR-021 regex ^[a-z][a-z0-9-]*[a-z0-9]$. All slugs share the worker-dashboard- prefix to disambiguate from future supervisor/analyst panel re-uses.

Most-actionable surfaces first. All spans in {1, 2, 3, 4, 6, 12} per ADR-021’s BREAKPOINT_SPANS (crates/canopy-composition/src/manifest.rs:107). Each row sums to exactly 12.

row is a required field on ComposedItem (crates/canopy-composition/src/types.rs:122 — pub row: u8). The loader groups items by row to enforce the per-row 12-span maximum (loader.rs:265). Every defaults/baseline item MUST declare row.

Per-panel default_span matches the table value above; allowed_spans = [3, 4, 6, 12] for every list-style panel (positions 2-12); allowed_spans = [12] only for the hero (position 1). The chosen default_span is always a member of allowed_spans (per manifest.rs:204 validation).

Each panel’s [data] block declares source + endpoints (one or more upstream URLs with {param} substitutions). The handler resolves {user_id} from the parsed-UUID worker session (SessionData.worker_id).

Per crates/canopy-composition/src/manifest.rs:189-191, endpoints array MUST be non-empty (EmptyEndpoints rejection). Panels whose real endpoint is not yet wired declare a placeholder endpoint string in their manifest AND their Rust fetcher constructs the panel Template struct with state = "empty" instead of hitting the network. Replacing the placeholder is a one-line edit when the FU lands.

Follow-ups filed BEFORE commit per feedback_no_deferral_accountability. See Step 8.

The #[canopy_plugin] proc-macro expands include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/", manifest)) — CARGO_MANIFEST_DIR is the crate root (services/canopy-web/). Per-panel Plugin.toml files must be referenced via crate-relative paths.

Layout:

#[canopy_plugin] attribute per panel:

The path is verbose but unambiguous and survives the macro’s CARGO_MANIFEST_DIR resolution. Each plugin struct is a unit struct; the macro doesn’t depend on it having fields.

Per-panel partials cannot share a single panel context because askama {% include %} renders in the parent’s context. To let each panel template declare exactly the fields it needs, each panel is its own #[derive(Template)] struct that renders to a String in Rust; the parent worker.html only emits the pre-rendered HTML via {{ panel.html|safe }}.

Each panel’s panels/{slug_underscored}.rs exposes:

The fetcher does:

RenderedPanel shape (in panels/mod.rs):

No PanelData / PanelState enum is needed — state lives inside each panel’s Template struct as state: &'static str.

The handler in services/canopy-web/src/api/dashboard.rs maps each composed.items[i].item.0 to its fetcher via a match in services/canopy-web/src/dashboard/panels/mod.rs::dispatch_fetch:

All 12 dispatches in a single render are fanned out via futures::future::join_all. Service identity: per ADR-019 the handler calls clients.with_service_identity(&svc_token).await ONCE before the fan-out (mirroring current dashboard.rs:107). Each panel’s Plugin.toml declares data.auth = "service_class" (v1 — user-JWT pass-through deferred per ADR-019 per-panel auth-mode hook). Unknown-slug fallback lives in a single unknown_panel partial that renders an error_block (unknown_panel::render precomputes the error text + state).

Note on data.timeout_ms: the manifest field is declarative for v1; the underlying InternalClient has a hardcoded 5-second reqwest timeout (services/canopy-web/src/clients.rs:37). Wiring per-panel timeout from manifest is FU-9.

Each panel partial has its OWN #[derive(Template)] struct (no shared panel context). All strings the template references are precomputed in the fetcher — see Decision 10’s "convention for these panels" note on the precompute discipline.

Common fields every per-panel Template struct carries:

Each templates/dashboard/panels/{slug_underscored}.html:

The fields state, label, count_text, error_text are not nested under a panel object — they’re top-level on the per-panel Template struct. This is what makes the per-panel struct independent of the parent worker.html template.

required_states per panel manifest declares ["empty", "error", "populated"]. Loading state is dropped from manifests because v1 renders server-side once; htmx refresh + loading skeleton land in a Stage-5 follow-up issue (FU-7).

Stage 1 primitive signatures (verified at services/canopy-web/templates/_primitives/orchard.html):

The composition loader’s actual signature (crates/canopy-composition/src/loader.rs:111-119):

Existing canopy-web composition handlers (api/composition.rs:562) source the idp via composition_loader.idp_for(&juris).await (this method does exist on CompositionLoader).

Required main.rs rewiring — three extensions are currently NOT globally available on the outer router and MUST be added before the dashboard handler can compile:

These rewirings live in Step 3’s main.rs section (Step 3).

WorkerDashboardTemplate struct fields are explicit (per base.html’s expectations at services/canopy-web/templates/base.html):

Empty composition (zero items after merge) renders a single error_block ("Dashboard composition has no panels — contact your administrator."). Shouldn’t happen in practice; defaults always ship 12 items.

Deviation from earlier plan iterations: the originally-stated symmetry between crates/canopy-composition/defaults/worker_dashboard.json and the Georgia baseline TOML was not achievable. Populating defaults/worker_dashboard.json with 12 items broke canopy-composition’s tests/loader_test.rs (7 tests) because they construct fresh CompositionLoader instances against empty TestPluginSource collections — the 12 worker-dashboard plugins are linkme-registered in canopy-web, not in canopy-composition’s test binary. Populating defaults would force every canopy-composition test to inject 12 dummy plugin definitions.

Resolved by keeping defaults/worker_dashboard.json empty (matches the other 4 surfaces) and putting all 12 items in rulesets/georgia/composition/worker_dashboard.toml alone. Per ADR-022 RFC 7396 array replacement semantics, the baseline items overlay wins → Georgia gets the 12 panels regardless. New jurisdictions adding their own baseline TOML pick up no panels until they declare them — which is correct: each jurisdiction must own its composition explicitly.

defaults.rs keeps a single defaults_ship_empty_items_jurisdiction_baselines_override test covering all 5 surfaces' empty-items invariant. The plan’s earlier stage5_worker_dashboard_defaults_have_12_panels sibling test was not added.

Test changes in crates/canopy-composition/src/defaults.rs:

AuthenticatedWorker(pub SessionData) is a tuple struct — services/canopy-web/src/session.rs:259. Field access is worker.0.role, NOT worker.role. Handler uses AuthenticatedWorker(session) destructure pattern.

WorkerRole variants (session.rs:18-24): Caseworker, EligibilitySpecialist, Supervisor, QualityControl, Admin.

idp.toml roles (rulesets/georgia/idp.toml): eligibility_worker, supervisor, jurisdiction_admin, qc.

Mapping (lives at services/canopy-web/src/dashboard/role_map.rs):

RoleSlug is pub struct RoleSlug(pub String) (crates/canopy-composition/src/types.rs:85) — no ::new constructor; wrap the string directly.

Caseworker + EligibilitySpecialist intentionally collapse to the same slug — Keycloak’s eligibility_specialist claim widens the realm role beyond caseworker but their composition view is the same in v1. Stage 5 #496 (supervisor + analyst dashboards) introduces role-layer overrides that distinguish supervisor and analyst (the eventual EligibilitySpecialist slug); QC + admin overrides land alongside per design.

In v1 ALL 4 idp.toml roles (eligibility_worker, supervisor, qc, jurisdiction_admin) see the same composition because every panel manifest lists all 4 in required_roles (Decision 11). The role-filter (crates/canopy-composition/src/role_filter.rs:22) silently drops items whose plugin permission excludes the request role, so under-permissioning a panel would produce a partial-dashboard render — Decision 11’s permissions list is deliberately broad to avoid that.

user_id derivation: SessionData.worker_id: String is the Keycloak sub claim. If it parses as a UUID, wrap in Some(UserId::from(uuid)); otherwise None (logged WARN once). The composition loader handles None correctly (skips the user-layer merge).

jurisdiction: source from Extension<Arc<WebConfig>> — web_config.jurisdiction: String. canopy-web is single-tenant per ADR-005 v1; multi-jurisdiction = #516.

No new inline style= attributes. No new inline <script> blocks. All per-panel styling uses existing Orchard tokens + utility classes. New CSS additions land in services/canopy-web/static/css/canopy-web.css per existing convention.

Panel partials use {% call o::panel_frame(…​) %}{% endcall %} block form (askama 0.15 requires {% endcall %}; the askama-015 quirks memory captures this for future reference). Convention for these panels: precompute strings in the fetcher; do not invoke methods inside panel templates. (Note this is a local convention — askama does support method calls and current dashboard.html:55 uses work_queue.is_empty(). The precompute discipline keeps panel partials shape-pure and helps tests assert against handler-side data.)

Every panel’s Plugin.toml follows this exact shape. (Field order matters for serde-toml round-trip but parse is order-insensitive — the example below is the recommended order.)

Panels whose data isn’t yet wired (FU-1, FU-2, FU-3, FU-4, FU-5, FU-6) declare their future endpoint as a placeholder. The fetcher constructs the panel Template with state = "empty" and never hits the network; updating the fetcher to a real call when the FU lands is the only change needed (manifest unchanged).

Per-panel deviations from the exemplar (the only fields that vary):