Skip to main content

h.work Documentation

Internal product documentation for the h.work platform — AI-augmented operations for delivering managed AI+Expert services.

🚀 Quick Start​

📚 SectionWhat you'll find
🎯 FeaturesFeature specs, requirements, and implementation status
🎨 DesignInformation architecture, user flows, views by role
📡 API ReferenceComplete API documentation with endpoints
🧪 User StoriesP0/P1/P2 user stories by role (Client, Expert, AM, Superadmin)

📋 Key Documents​

Recently Updated (2026-06-04)​

  • Documentation Fixes (archived) — Summary of doc updates landed on 2026-05-22.
  • Implementation Status — What's built vs. gap analysis
  • API Reference — Updated with 50+ endpoints
  • 2026-07-13 — Railway→ECS supersession: ADR-038 formally supersedes ADR-003 for staging/prod (prod cutover #701 closed 2026-06-15). Railway remains canonical for dev only (#1233). Swept stale "migrating Railway → ECS" claims in PRODUCT_OVERVIEW.md and USER_OPERATIONS_MANUAL.md.
  • 2026-06-02 → 2026-06-04 architecture & infra sweep:
    • New ADRs accepted: ADR-024 Haystack migration (supersedes ADR-004 + ADR-009 RAGflow), ADR-025 pgvector, ADR-026 OpenRouter routing, ADR-027 TypeORM-only, ADR-028 retire RailwayPerOrgProvisioner (implementation in PR #1584 / #1450).
    • Promotion flow: PR #1559 made dev → staging → main a CI-enforced required status check — see docs/promotion-flow.md.
    • Domain canonicalization (PR #1537): h852.work = dev, h853.work = staging, h.work = prod. Sweep any older docs using stale subdomain names.
    • Schema renames: PR #1602 — environment_profiles → client_briefs (DB-table-only as of 2026-06-04; API module rename tracked in #1199). PR #1604 — new correction_embeddings table (Phase 1 of learning-loop #1360; uses OpenAI directly for embeddings — flagged as a possible ADR-026 exception).
  • 2026-05-29 → 2026-06-02 audit-followup sweeps (#1265, #1280): ADR-020 isolation classification fully shipped end-to-end (#1132–#1153, expert_agent_messages table dropped, unified messages table live, osa_id FK on agent_runs / tool_calls); Lago billing live (#1069 wiring, #1105 lifecycle, #1155 webhook + FE, #1016 Phase-7 Stripe teardown — Stripe survives only as Lago's PSP); Stripe Checkout for client payment-method add-card (#1275, closes #1268); ADR-023 invite lifecycle accepted (#1286); Tavus integration rename completion (#1031 + #1280 — /ops/tavus/* is live, /ops/personas/* is 308-redirect-only).

Architecture & Design​

Operations​

  • Deployment Guide — Environment setup and deployment
  • Email Channel Setup — Gmail API + DWD configuration (primary, shipped 2026-06-05 PR #1722); Cloudflare worker fallback during 2-week soak (#1440/#1441)
  • Incident Response — On-call runbooks
  • Engagement Date Changes — AM runbook: what realigns billing automatically vs. when a Start Date / trial change on a billed subscription needs a manual Lago credit/back-bill (#894)

🏗️ Platform Overview​

┌─────────────────────────────────────────────────────────┬──────────────────────┐
│  CLIENT PORTAL (/client/*)              │  EXPERT WORKSPACE (/workspace/*) │
│                                         │                                 │
│  • Chat with Specialists                 │  • Queue (pending tickets)         │
│  • Thread management                    │  • Tasks (agentic plan review)      │
│  • Settings (Team/Channels/Billing)     │  • Analytics                        │
│                                         │  • Personal settings                │
└─────────────────────────────────────────────────────────┴──────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────┐
│  OPS PORTAL (/ops/*) — AM + Superadmin                       │
│                                                                │
│  • Clients (AM: assigned; SA: all)                            │
│  • Inbox • Queue (SA only) • Analytics • Health • Billing       │
│  • Team (SA only) • Settings                                   │
└─────────────────────────────────────────────────────────┘

🧬 Terminology​

TermDefinition
SpecialistClient-facing AI persona (e.g., "Bob") that clients chat with
Agent runtimeInternal sandboxed AI runtime infrastructure behind a Specialist (NestJS+FastAPI service). This is infra terminology only — never use "Agent" as a synonym for Specialist in user-facing copy.
ExpertHuman reviewer who supervises AI output and handles escalations
AMAccount Manager — onboards and manages client orgs
SASuperadmin — cross-org access and platform operations

⚠️ Important Notes​

API Route Migration

  • /am/* routes are legacy — prefer /ops/* where available
  • Documentation updated: 2026-05-22
  • See API Reference for current endpoints

Expert ↔ Org Access Model (current)

  • Expert pools were removed 2026-05-03.
  • The previous direct table org_experts was deprecated 2026-05-22 per ADR-007.
  • The canonical model is now expert_access — a dual-scope grant table:
    • scope='org' — Expert can see all of one Org's data.
    • scope='specialist' — Expert can see one (Org × Specialist) slice.
  • All new code must use ExpertAccessService. org_experts is readable for back-compat during the #537 transition and is removed in #540 after soak.
  • See Implementation Status § 13 and ADR-007.

📖 Contributing​

This documentation is auto-rendered from the /docs folder of the humanwork repo. Edit markdown files directly — changes deploy on push to dev.

Quick edit links:

Last major update: June 4, 2026

Last updated on by franky