Dispatch Docs

Appearance

Dispatch — Project Overview & Architecture Reference ​

This document captures the project context, architecture, and conventions for the Dispatch design system. It mirrors the guidance in the repo's CLAUDE.md and is intended as a standalone reference for contributors.

What this repo is ​

Dispatch is the operating system for an AI-augmented BPO cooperative: member-partners are matched to client mandates, complete tasks (validated by AI + managing partners), earn GACx (a $1-pegged on-chain credit), run pulse surveys / OKRs, and govern via one-member-one-vote proposals.

This repository is not the shipping app — it is a design system + visual/behavioral reference: the theme/token source of truth plus a set of vanilla HTML/CSS/JS templates that the real app follows. The production app is built separately on the latest Angular (standalone + signals, zoneless, SSR/SSG). When asked to "implement in Angular," treat this repo as the spec, not the codebase — the full mapping is in design-system/design.md §8.

All real content lives in design-system/. The git root only tracks README.md + .gitignore; design-system/ is currently untracked. Run all commands from design-system/.

Authoritative docs (read these first) ​

  • design-system/design.md — full product + architecture spec, and the Angular handoff (§8) with confirmed decisions (bootstrap, routing, SSR-safe patterns). The source of truth for intent.
  • design-system/STATUS.md — live "pick up from here" working notes: what's built, what's open, cache-buster versions in use, recent gotchas. The source of truth for current state. Update it as work progresses.

Commands (run from design-system/) ​

bash
npm run build    # tailwindcss CLI: src/app.css -> dist/app.css (minified) — the real build
npm run dev      # same, --watch

There is no test runner and no lint script. To preview a template, open its index.html directly in a browser — pages self-bootstrap by CDN-loading Tailwind + DaisyUI at runtime (no build step needed for preview). The _ds_*.{json,js} files and _adherence.oxlintrc.json are generated tooling artifacts (design-system harness); do not hand-edit them.

Architecture ​

Bootstrap chain (every page) ​

Each page loads one line: templates/<slug>/ds-base.js. That shim resolves the project root and loads the shared runtime app-shell.js, which:

  1. injects the Tailwind v4 browser build + DaisyUI v5 from CDN,
  2. loads styles.css + bespoke.css + brand fonts,
  3. mounts the connection indicator pill on <body>,
  4. registers the PWA service worker + manifest.

ds-base.js is the single line a consumer edits to point at the design system.

Theme is defined in THREE places — keep them in sync ​

A change to any brand token (color/radius/font) must be mirrored in all three:

  1. styles.css — [data-theme="dispatch"] / [data-theme="dispatch-dark"] CSS vars (preview).
  2. src/app.css — the same values via @plugin "daisyui/theme" (production build).
  3. app-shell.js — an inline type="text/tailwindcss" @theme block (so the browser runtime generates bg-primary, font-serif, … utilities).

Two themes: dispatch (light, default) and dispatch-dark. Toggling sets data-theme on <html> (desktop) or on #device-screen (mobile); persisted in localStorage under dispatch_theme.

CSS layering ​

  • DaisyUI components (btn, card, navbar, progress, toast, …) are used as plain classes — these port to Angular templates unchanged.
  • bespoke.css holds everything DaisyUI doesn't: device frame, solar loader, connection pill, and the admin styles (.adm-* / .reg-* / .dash-*). Note design.md references an admin.css that does not exist — admin styling lives in bespoke.css.

Templates ​

  • templates/desktop/ — member web app: navbar + 6 tabbed panels (Dispatch / Mandates / Pulse / OKRs / Vote / GACx Wallet) + the Dispatch AI chat.
  • templates/mobile/ — 390px device frame, dark interior, 5 bottom-tab screens.
  • templates/admin/ — back-office (index.html + admin.js) + register.html (first-run onboarding). Simulated Google Workspace SSO gate.

Controllers are vanilla JS with inline onclick="" handlers and direct DOM manipulation — there is no framework or reactive state. (In the Angular port, onclick → (click), state → signals.)

Admin CRUD engine (templates/admin/admin.js) ​

A single SCHEMA object drives table columns, the create/edit modal fields, stat strips, and seed data for each entity (orgs, mandates, tasks, votes, users). Adding a field or entity = edit SCHEMA only. State persists to localStorage:

  • dispatch_admin_v3 — CRUD store. Bump the version suffix to reseed with fresh demo data.
  • dispatch_notifs_v1 — notifications. dispatch_pending_users — registrations awaiting merge.
  • sessionStorage dispatch_admin_authed — simulated SSO session.

Domain rules to preserve (web + Angular must agree) ​

  • Completion is derived live from a mandate's tasks, weighted by status: Passed 100% · Live 60% · Progress 50% · Queued/Failed 0%.
  • Skill scores are on a 0.00–10.00 scale, 2 decimals, with a self-assessed score and a separate MP-validated score; validation happens after the fact in the Validation queue, not at registration.
  • Each user-skill carries a coefficient (default 0 = unassigned) for scheduling, set by an MP later.
  • Dispatch AI chat is wired to the in-prototype bridge window.claude.complete with a canned fallback if unavailable.

Conventions & gotchas ​

  • Cache-busters: preview pages pin versions in the script src (e.g. admin.js?v=8, ds-base.js?v=7); the ?v= propagates HTML → ds-base → app-shell → CSS. Bump the version when stale behavior appears after an edit. Current values are tracked in STATUS.md.
  • No raw hex or px in styles — the adherence ruleset flags raw #rrggbb and Npx; use design tokens via var(--color-*) / the --radius-* / --size-* tokens. Don't import app-shell.js / postcss.config.mjs / service-worker.js internals directly.
  • Template-string trap: avoid backticks or ${} inside HTML comments that sit inside a JS template literal (this broke register.html twice — the backticks terminate the outer string).
  • Page background: the Tailwind/DaisyUI runtime injects html,body{background:transparent} after our sheets; styles.css beats it with the higher-specificity html body{background:var(--color-base-100)}. Keep that rule if touching global background.
  • Everything backend-shaped is simulated/local: SSO sign-in, the connection heartbeat (pingInfra() — mock), notifications, and all data (localStorage). These become real in the Angular build; don't mistake them for live integrations.