Product Overview — h.work

Purpose. A single top-down view of what h.work is, what it does, how mature each part is, and where it's going. This is the missing "product master plan" layer that sits above the detailed trackers. New contributors, AMs, and stakeholders should be able to read this one document and understand the product end-to-end.

This doc is curated, not canonical. It deliberately summarizes and links rather than duplicates. When this doc and a more specific source disagree, the specific source wins:

What is/isn't built → implementation-status.md (the build source of truth)

Live backlog / priority → GitHub Issues (the roadmap source of truth — FUTURE_REQUIREMENTS.md lags it)

Architecture decisions → docs/decisions/ (34 ADRs)

Open product calls → decisions/OPEN_DECISIONS.md

中文版: PRODUCT_OVERVIEW.zh.md Last reviewed: 2026-06-30 · against origin/dev @ 569d7cbe.

1. What h.work Is

h.work is an internal platform for Humanity Protocol (HP) used to deliver a managed "AI + Expert" service to client companies.

A client (an employee at a client org — e.g. Amy at Acme Financial) messages their assigned Specialist persona (e.g. Eleanora Voss). The AI agent drafts a reply; the draft is routed to an HP Expert (a real human, e.g. David Kim) who reviews and sends it as the Specialist. The client experiences one consistent, professional persona; the human reviewer is never exposed.

It is not a helpdesk product that clients deploy to support their own end-customers. It is HP's own operational platform for running this managed service across many client orgs.

Principle	What it means in practice
Human-in-the-loop by default	`autoRespondThreshold = 101` (never auto-send). Every AI draft goes to an Expert. AMs tune the threshold per client during onboarding.
Persona integrity	The client only ever sees the Specialist (name, avatar, email alias). The Expert's identity is never leaked — not in chat, not in email headers, not in BCC.
Multi-tenant, layered isolation	Isolation is per resource class, not one global boundary. PII / conversations / queue items are scoped Org × Specialist; KB is K1 (tenant) + K2 (global-for-Specialist); see ADR-020.
Fail-open on agent errors	If the agent is unreachable, return a safe escalation and queue for an Expert — never surface a 500 to the client.

Who uses it (roles)

Role	Surface	Who they are
Client (`org_admin` / `org_member`)	`/client/*`	Employees at a client company. Chat with their Specialist.
Expert	`/workspace/*`	HP human reviewers. Review/edit/send AI drafts as the Specialist.
AM (Account Manager)	`/ops/*`	HP staff who onboard and manage client orgs, assign Specialists.
SuperAdmin	`/ops/*`	Platform administrators. Create/manage Specialists & Experts.
Specialist	— (not a login)	An AI persona, not a user account. Assigned to clients.

Terminology is load-bearing — see the table in CLAUDE.md and features/roles-and-permissions.md. Using the wrong word (agent/bot/workspace/tenant) is a code-review signal.

2. The Core Flow

The whole product is organized around one loop: a client message becomes a reviewed, persona-attributed reply.

Client message  ──►  Inbound channel (web / email / WhatsApp / Slack / Telegram)
                         │  dedup + org×specialist routing
                         ▼
                 ConversationsService  ──►  Agent Service (POST /v1/chat, Hermes/RIG runtime)
                         │                        │  retrieval (KB) + persona + (planned) tools
                         ▼                        ▼
                 Structured JSON: { reply, confidence, risk_level, flag_for_review }
                         │
            confidence < threshold OR risk ≥ HIGH  ──►  ExpertQueueItem
                         │                                   │
                         ▼                                   ▼
                 Socket.io push to Experts          Expert reviews in /workspace
                 (8s polling fallback)              accept / edit / write-from-scratch
                         │                                   │
                         └──────────────►  Reply sent AS the Specialist  ──►  Client
                                           (Gmail DWD / channel dispatcher, 3-layer protected)

Detailed treatment: features/expert-queue.md, features/auto-reply.md, features/conversation-status-lifecycle.md.

3. Architecture at a Glance

Service	Stack	Responsibility
api/	NestJS 11 (TypeScript), PostgreSQL 16 + pgvector, TypeORM, Socket.io	Control plane: REST + WebSocket, auth, conversations, expert queue, billing, channels, KB retrieval.
agent/	FastAPI (Python 3.11), Hermes/RIG runtime, GPT-4o	AI drafting, risk classification, tool calling.
frontend/	Next.js 16 + React 19	Client portal (`/client`), Expert workspace (`/workspace`), unified Ops surface (`/ops`).
rag/	Haystack 2.x + Hayhooks, pgvector	Retrieval pipeline (hybrid BM25 + vector + RRF + rerank).

Deployment is multi-instance active-active (staging + prod) — a hard constraint. No in-process shared state, no setInterval cron, no sticky sessions; cross-pod coordination via Redis / Postgres / BullMQ. See ADR-018 and the Deployment Model section of CLAUDE.md.

Infra: staging + production run on AWS ECS Fargate (#701, closed 2026-06-15; formal decision record: ADR-038). Dev remains on Railway (deliberate, #1233). RAG runs on ECS Fargate in staging+prod too (ADR-024).

4. Functional Module Blueprint

The product decomposes into the modules below. Status is a rolled-up summary — per-feature truth lives in the linked implementation-status.md section.

#	Module	Maturity	One-line scope	Deep dive
1	Auth & Roles	🟢 Done	Email/OTP login, 2FA, Google SSO, JWT, two-tier roles, Postgres RLS	§1 · roles
2	Client Onboarding	🟢 Done	AM validation gate → 3-step client SPA → active org	§2 · onboarding
3	Client Portal Chat	🟢 Done	Threaded chat, Specialist persona display, channel badges, trial banner	§3
4	Expert Workspace	🟡 Core done	Queue, AI suggestion + confidence/risk, accept/edit/send, internal notes	§4 · workspace
5	Conversation Mgmt	🟢 Done	Status lifecycle, snooze, assignment, full-text search, audit, SLA tracking	§5
6	Channel Adapters	🟡 Mixed	Email (Gmail DWD) + WhatsApp + Telegram live; Slack partial; Teams/WeChat stub	§6 · channels
6a	Integrations (Nango + bespoke)	🟡 Framework	Nango OAuth catalog; Shopify/Amazon live; QuickBooks/Xero unwired; Jumio skeleton	§6a
7	Specialist Mgmt	🟢 Done	Create/assign Specialists, per-OSA email alias, per-org confidence threshold	§7
8	Notifications & Real-time	🟡 Partial	Socket.io + SSE + in-app notifications live; push / email / prefs pending	§8 · notifications
9	Analytics & Reporting	🟡 Partial	SA analytics live; Expert leverage done; per-org gross-margin pending	§9
10	Billing & Subscriptions	🟢 Done	Lago, per-Specialist monthly rate, client + Ops surfaces, Stripe-as-PSP	§10 · billing
11	Outbound Webhooks / API	🔮 Future	Per-org signed event subscriptions — not started	§11
12	Mobile	🟡 PWA only	Responsive PWA shipped; native app + push not built	§12
13	Knowledge Base & Learning	🟢 Core done	K1+K2 KB, hybrid retrieval+rerank, client KB UI, correction capture	§13 · ADR-008
14	Platform Ops & Admin	🟡 Partial	Health, metrics, audit, impersonation, DLQ admin; tool-permission UI pending	§14 · audit
15	AI Agent Runtime	🟡 Evolving	Hermes/RIG chat runtime; business tools not yet on chat path; SSE partial	§15 · AGENT_ARCHITECTURE
16	Dogfood (Acme/Eleanora/KYC)	🟡 Partial	First dogfood org; Jumio E2E blocked on sandbox account	§16

Maturity legend: 🟢 Done (production-usable) · 🟡 Partial / mixed · 🔮 Future (not started).

5. Current Progress Snapshot

Phase: pre-launch ramp toward the first paying customer ("Kaito-launch").

What's solid today (the happy path works end-to-end):

A client can be onboarded, chat with a Specialist over web/email/WhatsApp/Telegram, the AI drafts, an Expert reviews and sends as the Specialist, and the org is billed per assigned Specialist via Lago.
KB retrieval, multi-tenancy/RLS, audit, real-time push, circuit-breaker/DLQ outbound protection, and graceful shutdown are all in place.

Where the edges still are (highest-leverage gaps):

Specialist professionalism is unmeasured — quality rests on a hand-written prompt + good retrieval; no domain-accuracy eval, no grounding check, Expert-edit signal is discarded. (This is the thesis of ADR-033.)
Business tools aren't on the live chat path — the Specialist can talk about KYC/orders/finance but can't fetch real data yet.
Channel reliability/observability — ~30k records backlogged in the dispatch DLQ (#3444); limited per-channel metrics; some inbound bugs (cross-channel bleed #3558, WhatsApp outbound #3506).
Prod hardening — observability stack (SigNoz/Langfuse/PostHog #1230/#1231/#1232). Railway → ECS migration (#701) closed 2026-06-15 — see ADR-038.
Coverage — frontend test coverage is thin (#171).

~87 open issues at last review; for live counts and priority, trust GitHub, not this doc.

6. Roadmap (Now / Next / Later)

Organized by intent, not date. Each item links its tracking issue/epic. Priority labels live on GitHub; this is the strategic grouping.

Now — unblock the first paying customer & stop the bleeding

Kaito pre-launch UAT smoke checklist — #1198
Channel reliability — DLQ backlog #3444, WhatsApp prod pairing/outbound #3169/#3506, cross-channel bleed #3558
Expert workspace P0 bug — AI answer pane mis-pairs answers #3504
Onboarding stability — invite-link flow breakage #3520/#3522

Next — make the Specialist genuinely professional + observable

★ Professional Specialist Architecture — ADR-033 / Epic #3322. Layered pipeline; measurement-first. First brick: capture Expert edit-diff signal #3323.
Wire business tools to the chat path — KYC/Jumio #230, QuickBooks/Xero/finance tools #176
Observability stack — SigNoz APM #1230, Langfuse LLM traces #1231, PostHog product analytics #1232, channel observability epic #3532
Notifications completion — push + email + prefs #170
Expert acquisition pipeline — self-signup + AI screening + activation #1080
Per-org gross-margin — dollarized labour+infra cost #3196
Frontend test coverage — #171

Later — breadth, polish, strategic surfaces

Mobile — responsive audit #2978, native app, deep-linking
More channels — Microsoft Teams #122, WeChat #378, outbound media #559
Settings & transactional-email overhaul — #1690, #1258
Outbound webhooks / API extensibility — client CRM/ticketing integration (strategic, untracked)
Contact Profiles — unified cross-conversation client record (strategic, untracked)
Outbound Campaigns — Specialist-initiated outreach, after inbound loop is stable (strategic, untracked)
Correction → KB self-improvement loop — close the flywheel (#303, #323)

7. Open Product Decisions

These need a product/E call before the dependent work can ship cleanly. Canonical list (with options + owner): decisions/OPEN_DECISIONS.md.

ID / Issue	Decision needed
OD-12	Should clients see a read-only "review posture" label (e.g. "Always Reviewed by Expert")?
OD-10	Lago billing model: free `plan_per_rate` vs. premium-licensed `plan_overrides`.
OQ-205	Closed (2026-07-07, CD-30) → ADR-037: runtime read-only toward Specialist assets; the loop proposes, humans approve. (Was: may a Specialist agent write skills back to R2?)
#154	May AMs mutate client team members?
#3501	Storage scope for Expert access to agent-generated files (per-agent / per-org / per-conversation).
#3551	"Call Specialist from chat" (Tavus) with prior-chat context — product decisions pending.

8. Where to Go Deeper

You want…	Read
Demand validation, ICP/JTBD, competitive positioning (why we win)	`PRODUCT_STRATEGY.md`
Exact build status of any feature	`implementation-status.md`
Live backlog & priorities	GitHub Issues → `FUTURE_REQUIREMENTS.md`
Why an architectural choice was made	`decisions/` (ADRs)
A specific module's design	`features/` (26 module docs)
UI/IA, flows, per-role views	`design/` (`INFORMATION_ARCHITECTURE`, `VIEWS_BY_ROLE`, `USER_FLOWS`)
User stories (C-/E-/SA- IDs)	`user-stories.md`
Launch readiness	`mvp-launch-checklist.md`
Glossary & non-obvious terms	`CLAUDE.md` · GLOSSARY

Maintenance: review on each launch-phase shift or when a module crosses a maturity boundary. Keep this doc thin — push detail down into the linked sources and link back up.

1. What h.work Is​

Who uses it (roles)​

2. The Core Flow​

3. Architecture at a Glance​

4. Functional Module Blueprint​

5. Current Progress Snapshot​

6. Roadmap (Now / Next / Later)​

Now — unblock the first paying customer & stop the bleeding​

Next — make the Specialist genuinely professional + observable​

Later — breadth, polish, strategic surfaces​

7. Open Product Decisions​

8. Where to Go Deeper​