Skip to main content

Architecture docs

Authoritative architecture references for the Human.work runtime control plane, sandboxing, and isolation model.

Read order​

  1. ISOLATION_SANDBOXING_BINARIES.md — the layered isolation deck. Compiled runner + Zig capability shell + no ambient secrets + OS/container sandbox + control-plane policy. Defines the what and why. (Author: Alex Dankov, 2026-05-20.)
  2. SPLINTER_PORTING_PLAN.md — what to port from Splinter / Rig (humanity-org/rig) into Human.work, and what to leave behind. End-state five-layer architecture. (Author: Alex Dankov, 2026-05-20.)
  3. RIG_HARD_CUT_RUNTIME_PORT_PLAN.md — the implementation/cutover plan that lands the above. PR #696 (merged 2026-05-25) implements milestones 0–9; the issue-disposition matrix tracks per-issue status.
  4. workspace-lifecycle.md — Google Workspace tenancy, per-(Specialist × Client) mailbox provisioning, scoped DWD service accounts, and app-code domain enforcement. Realizes the "no ambient secrets" + control-plane credential proxy principles from doc 1 for the Workspace surface. Anchors #678 / #679 / #680–#684 / #587. (Author: Emanuele, 2026-05-28.)
  5. EXPERT_ACCESS_MODEL.md — dual-scope Expert access model on the single expert_access table (scope='org' | 'specialist', UNION semantics). Realizes ADR-007. org_experts was dropped 2026-06-05 via PR #1711 PR 4 (commit 1a904fa5); expert_access is now the sole grant table. New code uses ExpertAccessService. (Refreshed 2026-06-02 via #924; banner updated 2026-06-06.)
  6. HUMANWORK_SANDBOX_SUPERVISOR.md — draft design for the target sandbox supervisor substrate (bwrap + supervisor process owning the evidence contract). Hooks ADR-022. Realizes layer 4 ("OS/container sandbox") from doc 1. (Refreshed 2026-06-03.)
  7. subdomain-routing.md — when h.work uses the platform host (NEXT_PUBLIC_APP_DOMAIN, per-env: dev.h852.work / app.h853.work / app.h.work) vs a client org portal subdomain ({slug}.{NEXT_PUBLIC_HWORK_DOMAIN}): host taxonomy, the five routing rules (login/logout on the platform host, clients always routed to their org portal, reserved-slug mirroring, middleware slug-resolve, cross-subdomain cookie + JWT), and the getPlatformLoginUrl / getPlatformUrl / getPortalUrl / getSubdomainSlug helper map. Anchors #2616 / #2870 / #3025 / #3072 / #3076 / #3088.

Cross-cutting runtime surfaces​

Not part of the isolation deck, but referenced here for real-time control-plane behavior:

  • ../features/notifications.md — the AppNotification REST + Socket.io delivery pipeline (#915, closes #170): persistent /notifications store + /notifications Socket.io namespace, per-user room delivery, Redis multi-pod fan-out, and producers (billing / workspace-provisioning failures). Triage: ../runbooks/notification-failures.md.
  • alert-stack.md — end-to-end overview of the MVP alert stack (#1307): how CloudWatch (in-cluster signals → SNS → Slack-subscriber Lambda), Sentry (in-process exceptions + release health), and Better Stack (external synthetic uptime + on-call) compose into one paging surface. Who gets paged on what severity, cooldowns/de-dup, and the bypass path. Per-component reference: ../runbooks/observability.md.

Anchored issues​

Issues that depend on this architecture deck (read the deck before commenting on or closing any of these):

  • #332 — Compiled per-org policy enforcement (compiled runner + signed manifest layer)
    • status: local implementation scaffold in this branch; close only after runner-build/sign/store/pull CI and registry cutover merge.
  • #362 — Per-Org sandboxed agent runtime MVP (1:1 Org ↔ runtime)
  • #401 — Per-(Org × Specialist) sandboxed runtimes v2 (1:N + rotation)
    • status: local routing/schema/eval scaffold in this branch; close only after per-Specialist runtime routing is merged and nightly eval is green.
    • Update (2026-06-01): Phase 1 SHIPPED 2026-05-26 via #662 — per-(Org × Specialist) sandboxed agent runtimes are live in production. #401 remains open to track Phase 2 (rotation + warm-pool scale).
  • #237 — Cross-Org isolation eval nightly (must cover runtime tables + sandbox capability ops + control-plane endpoints + internal-role filter)
    • status: local nightly eval expansion in this branch; close only after staging secrets are configured and nightly evidence exists.
  • #251 — Per-client-agent auth secret (no ambient secrets)
  • #625 — R2 client-data isolation (per-org buckets vs prefix-scoped + compensating controls)
  • #678 — Google Workspace lifecycle & per-Specialist scoped OAuth (per-(org × specialist) credential isolation)
Last updated on by Degen