iios/docs/IIOS_OVERVIEW_FOR_CEO.md

IIOS — Insignia Interaction OS

Phase-by-phase overview · who uses what · a real build (Yamuna Expressway support)

A plain-language walkthrough of everything built so far (P0 → P8), the SDKs each phase produced, who consumes them, and a worked example of building an Intercom-style support experience for the Yamuna Expressway portal on top of it. Written to be read top-to-bottom in ~10 minutes.

---

1. What IIOS is, in one paragraph

IIOS is one backend and a family of small SDKs that treat every interaction — a chat message, a support ticket, a routed community post, an AI suggestion, a scheduled meeting — as the same underlying object (an "Interaction") sitting inside a tenant scope, behind the same safety gates (who's allowed, whose consent, what policy), and emitting the same audit trail. Instead of building a chat app, then a separate ticketing app, then a separate meetings app — each with its own identity, permissions, and audit — we built the shared core once and then "earned" each product capability as a thin specialization on top. The result: a WhatsApp-community manager, a customer-support console, and a meeting assistant are the same system wearing different hats.

Why a CEO should care: every new product surface (support, community, meetings, AI) reuses the same identity, permission, consent, and audit spine — so each new capability is faster to ship and safe by construction, not safe by remembering to add checks. That's the moat.

---

2. The one big idea (and three rules that make it safe)

• Everything is an Interaction. A message is an artifact of an interaction; so is a ticket, a route decision, an AI summary, a meeting. One data spine, one audit log.
• Kernel + specializations. A tiny kernel (identity, scope, threads, events) is the foundation. Messaging, inbox, support, routing, AI, meetings are specializations that import the kernel — never the other way around. A build check (pnpm boundary) enforces this so the layers can't rot into spaghetti.
• Three safety rules baked in everywhere:
  1. Fail-closed — if the policy/consent check is unavailable or says no, nothing is written. Never an accidental "allow."
  2. Replayable & idempotent — the same event processed twice produces one result, so nothing double-charges, double-sends, or double-books.
  3. Preview / propose before act — risky things (forwarding to a group, AI decisions, recording a meeting) are previewed or proposed, and a human or a deterministic rule is the gate. AI can suggest; it never decides.

Today the external world (real WhatsApp, real AI models, real calendars, the real policy engine) is faked with deterministic stand-ins so we could build and prove the whole system offline. Turning those fakes real is the final phase (P9). This is the single most important framing for the CEO: the engine and all the product SDKs are built and demonstrable end-to-end; what remains is wiring them to real external providers and hardening for scale.

---

3. The phases at a glance

Phase	Capability	SDK / package produced	Who uses it	Live demo
P0–P1	Kernel — identity, tenant scope, threads, events, fail-closed gates	iios-contracts, iios-testkit, iios-service (kernel)	Foundation for everything (no direct end-user)	—
P2	Native messaging — threads, messages, read receipts, unread counts, realtime	iios-message-web	Any chat UI (customer↔agent, member↔member)	message-demo (5173)
P3	Inbox — "needs reply / needs review" work queue	iios-inbox-web	Agents & admins triaging work	message-demo sidebar
P4	Support — tickets, queues, agent availability, escalation, callback	iios-support-web	Support agents + customers asking for help	agent-demo (5174)
P5	Adapters — inbound webhooks (signed), outbound send (sandbox), delivery tracking	iios-adapter-sdk	Integration engineers connecting channels	adapter-inspector (5175)
P6	Routing / rules — forward messages between groups, preview-first, deny-by-default	iios-community-web	Community moderators / admins	route-admin (5176)
P7	AI proposal layer — classify, summarize, extract; budget-governed; propose-never-decide	iios-ai-web	Any surface wanting AI assist (human-gated)	ai-studio (5177)
P8	Calendar & meetings — schedule, attendee consent, transcript, summary, action items	iios-meeting-web	Support/scheduling; callback→meeting	meeting-studio (5178)
P9	(next) Production hardening — real providers, real policy/consent, scale, retention	—	Ops / platform	—

All of it runs on one NestJS service (iios-service) with one Postgres database (53 tables across 19 migrations), fronted by one low-level client (iios-kernel-client) that every React SDK is built on.

---

4. Phase by phase — what it does, who uses it, a real example

P0–P1 · The Kernel (the foundation)

What it adds. The vocabulary everything else speaks: a Scope (which org/tenant/app an interaction belongs to), a SourceHandle → ActorRef (turning "a WhatsApp number" or "a portal login" into a known actor), Threads and Interactions, a transactional outbox (every state change writes a business row and an event in the same transaction), and the fail-closed policy gate. SDKs. iios-contracts (the shared types, event names, and the platform-port interfaces), iios-testkit (deterministic fakes of the platform: session, policy/OPA, consent/CMP, identity/MDM, context, tokenization, capability broker), and the kernel inside iios-service. Who uses it. Nobody directly — it's the bedrock. Every other phase depends on it. Real example. A message arrives from WhatsApp number +9198…. The kernel resolves it to an actor within the Yamuna org's scope (not globally — no cross-tenant leaks), checks policy (fail-closed), and writes both the interaction and a interaction.normalized event atomically. If the policy check had been down, nothing would be written — no silent half-writes.

P2 · Native messaging — iios-message-web

What it adds. Real chat: open a thread, send a message, delivery/read receipts, unread counters, and realtime delivery over websockets. Who uses it. Any user-facing chat surface — a customer chatting with support, two members chatting, an agent replying. Real example. A Yamuna plot-buyer opens the portal's chat widget and types "When is my next payment due?" — that's a thread + message via iios-message-web; the agent sees it live, replies, and the buyer's unread count updates instantly. Demo: message-demo (5173).

P3 · Inbox — iios-inbox-web

What it adds. Turns raw messages into a work queue. When a message needs a human, an inbox item ("needs reply") is created for the right owner, with a state machine (open → done/snoozed/archived). Built by a projector reacting to message.sent — so the queue is always consistent with what was actually said. Who uses it. Agents and admins who triage: "what's waiting on me?" Real example. The buyer's "payment due?" message auto-creates a needs-reply item in the assigned agent's inbox; once the agent replies, it auto-resolves. No message silently falls through the cracks. Demo: the inbox sidebar in message-demo.

P4 · Support — iios-support-web

What it adds. The support product: tickets, queues, agent availability (go online/offline), assignment (least-loaded agent), escalation (customer ↔ support thread), and callback requests. This is the Intercom-shaped layer. Who uses it. Support agents (a dashboard) and customers (a "get help / request callback" widget). Real example. The buyer clicks "Talk to support." A ticket is created, auto-assigned to an available agent, and a dedicated customer↔agent thread opens. If it needs a phone follow-up, the buyer requests a callback — which later becomes a meeting (see P8). Demo: agent-demo (5174).

P5 · Adapters — iios-adapter-sdk

What it adds. The bridge to the outside world: inbound provider webhooks are signature-verified (HMAC), normalized into kernel interactions, and outbound replies go through a sandbox sender with delivery-attempt tracking and rate limiting. Channels modeled: WEBHOOK, EMAIL, WHATSAPP, PORTAL. Who uses it. Integration engineers who connect a new channel; the service uses it to ingest/emit. Real example. A WhatsApp message to the Yamuna business number hits the webhook adapter → verified → becomes the same kind of interaction as a portal chat, so support handles WhatsApp and web chat identically. Replies are recorded but sandboxed (no real send yet — that's P9). Demo: adapter-inspector (5175).

P6 · Routing & rules — iios-community-web

What it adds. Community message routing: route bindings (from origin → destination), a preview-first simulator that shows exactly what would be forwarded and to whom (with reason codes) without sending, decisions of ALLOW/DENY/REVIEW, deny-by-default for restricted audiences (e.g. a children's group), and admin approve/deny. Automatic routing only for explicitly safe rules. Who uses it. Community managers / moderators (WhatsApp-community use case). Real example. In a residents' community, an "after-hours party at 9 PM" post is flagged and routed to REVIEW for adults and DENY for the kids' group — a moderator approves before anything is forwarded. Nothing leaks by accident. Demo: route-admin (5176).

P7 · AI proposal layer — iios-ai-web

What it adds. AI that only proposes: classify (moderation flags), summarize, extract (candidate events/FAQ) — each output carries confidence, evidence citations, model/cost, and an abstention reason. A budget governor caps spend; the pipeline fails closed; and an AI flag can only push a routing decision toward REVIEW/DENY — never auto-approve. AI suggests; a human accepts. Who uses it. Any surface wanting assistance — support-reply drafts, meeting summaries, community moderation hints. Real example. The support agent gets an AI-drafted reply and a one-line summary of a long buyer thread; a community post is auto-classified so the moderator sees "flagged: after-hours event" with the evidence. The agent/moderator always makes the call. Demo: ai-studio (5177).

P8 · Calendar & meetings — iios-meeting-web

What it adds. Turns a callback into a real meeting: schedule + attendees, per-attendee recording consent, transcript, AI summary (reuses P7), and action items that flow back into the inbox. The safety spine: no transcript/summary/action-item exists until every attendee consents (and attendees marked "no visibility" are excluded from follow-ups). Meetings can also be born from an accepted AI-extracted event. Who uses it. Support/scheduling flows; anyone turning a conversation into a scheduled follow-up. Real example. The buyer's callback becomes a scheduled call. Both sides grant recording consent → the call is transcribed and summarized → "send revised payment schedule" becomes an action item in the agent's inbox. If the buyer declines recording, no transcript is ever created. Demo: meeting-studio (5178).

---

5. The SDK catalog — who consumes what

Think of it as three tiers:

Tier 1 — Foundation (engineers, not end-users)

• iios-contracts — shared types, event catalog, platform-port contracts. Everything imports this.
• iios-testkit — deterministic fakes + fixtures. Used by tests/QA to prove behavior offline.
• iios-service — the single backend API (NestJS) that contains every module (kernel, messaging, inbox, support, adapters, routing, ai, calendar).
• iios-kernel-client — the low-level REST + websocket client. Every React SDK is built on top of it; advanced apps can use it directly.
• iios-adapter-sdk — for authoring channel adapters (normalize + HMAC verify + sandbox send).

Tier 2 — Product React SDKs (front-end teams building app surfaces)

• iios-message-web — chat.
• iios-inbox-web — work queue.
• iios-support-web — tickets/escalation/callback/agent-availability.
• iios-community-web — routing rules + approvals.
• iios-ai-web — AI proposals + accept/reject.
• iios-meeting-web — scheduling + consent + summaries.

Tier 3 — Demos (proof surfaces, one per capability)

• message-demo, agent-demo, adapter-inspector, route-admin, ai-studio, meeting-studio.

Each product SDK is a handful of React hooks — a front-end dev wires the UI, the SDK handles auth, data-fetching, realtime, and talking to the one backend.

---

6. The worked example: an Intercom-style support experience for Yamuna Expressway

The goal: a plot-buyer in the Yamuna portal can chat with support, get AI-assisted answers, escalate to a human, and book a callback — and agents work it all from one console. (Yamuna already has the shell: a support-live widget, a support-token endpoint, and an assistant panel — currently pointed at the older support-service. IIOS is the upgrade path.)

How it maps onto what we've built:

Intercom-style feature	Built on	Status today
Customer chat widget in the portal	iios-message-web (P2)	✅ works now (in-portal, realtime)
"Get help" → ticket + route to an agent	iios-support-web (P4)	✅ works now
Agent console (queue of conversations)	iios-inbox-web + iios-support-web (P3/P4)	✅ works now
AI-suggested replies + thread summary	iios-ai-web (P7)	✅ works now (deterministic AI; real model = P9)
Escalate to human / assignment / availability	iios-support-web (P4)	✅ works now
Request a callback → book a meeting → notes/action items	iios-meeting-web (P8)	✅ works now (sandbox)
Also answer the buyer on WhatsApp/email, not just portal	iios-adapter-sdk (P5)	◐ modeled + sandboxed; real send = P9
Real AI answers from a real model	iios-ai-web + Capability Broker	◐ deterministic stand-in today; real model = P9

Do we have everything to build it now?

• For in-portal live support (web chat between buyer and agent, tickets, escalation, AI-assist, callback→meeting): yes — today. Every piece exists as an SDK against one backend. This is a buildable, demoable product right now, entirely inside the Yamuna portal, with no external providers required (portal chat rides the kernel + websockets).
• For true omnichannel (the same conversation over WhatsApp/email) and real AI answers: not yet — that's P9. The adapters and AI layer are built and proven with sandbox/deterministic stand-ins; P9 swaps in the real WhatsApp Business Platform, a real LLM via the Capability Broker, and the real policy/consent engines.

So the honest one-liner for the CEO: "We can build Yamuna's in-portal support product on IIOS today; making it answer on WhatsApp and with a real AI model is the next phase (P9). The whole thing already runs end-to-end locally with safety, consent, and audit built in."

Concrete build path for Yamuna (all with existing SDKs):

1. Point the portal's support-token endpoint at iios-service's dev/session token.
2. Buyer widget: MeetingProvider-style MessageProvider + useThread/useSendMessage (message-web) for chat; useCreateTicket/useRequestCallback (support-web) for "talk to a human."
3. Agent console: useInboxItems (inbox-web) + support-web queue/availability/assignment; useRunJob/useAiProposals (ai-web) for draft replies & summaries.
4. Callback → useSchedule + consent + useSummarize (meeting-web) to run and capture the call.
5. Later (P9): register a real WhatsApp adapter so the same conversations arrive from WhatsApp, and swap the deterministic AI for a real model.

---

7. What's real vs. simulated today (say this plainly)

Area	Today	Becomes real in
Core engine, identity, scope, audit, events	Real	—
All 8 product capabilities (chat→meetings)	Real logic, proven by tests + demos	—
Outbound to WhatsApp/email	Sandbox (recorded, not sent)	P9
AI answers	Deterministic golden model (no real LLM)	P9
Policy / consent / identity resolution	Faked deterministic ports	P9
Calendar/Zoom providers	Simulated sync	P9
Multi-tenant scale, retention, SLOs	Not yet	P9

Proof it works: 192 automated tests pass; every capability has a runnable demo and an end-to-end smoke script; the layer-boundary check enforces the architecture.

P9 has begun (real providers). A production chat app (chat-web) now runs on IIOS with real Supabase login (the session port verifies real OIDC tokens via JWKS — the first stubbed port turned real), plus richer chat built generically on the kernel: emoji reactions, pinned & saved messages, @mentions → inbox, and media sharing (images/video/audio/docs on a swappable storage port). Each was a thin, generic addition — no chat-specific logic in the kernel — which is the reuse thesis paying off.

---

8. What to actually show in the room

1. message-demo (5173) — two people chat in realtime; a needs-reply item appears in the inbox. "This is the chat + work-queue spine."
2. agent-demo (5174) — a customer escalates; a ticket auto-assigns to an agent. "This is support."
3. ai-studio (5177) — run classify/summarize on a message; see confidence + evidence; accept a proposal. "This is AI that proposes, never decides."
4. meeting-studio (5178) — schedule a meeting; try to transcribe without consent (blocked), grant consent (works), get a summary + action items. "This is consent-safe meetings."
5. route-admin (5176) — simulate forwarding a flagged post; watch it deny to the kids' group. "This is safe community routing."

Narrative arc for the CEO: one engine → chat → inbox → support → channels → community routing → AI → meetings, each a small SDK, each safe by construction, all demonstrable — with P9 (real providers + scale) as the clearly-scoped remaining work.

---

Appendix — repo facts: 11 packages, 6 demo apps, one NestJS service, 53 Postgres tables across 19 migrations (kernel → messaging → inbox → support → adapters → routing → ai → calendar → annotations/mentions → media). Boundary-enforced dependency law; 192 passing tests; 8+ end-to-end smoke scripts. First real-provider swap live: Supabase auth (JWKS-verified) + a media storage port.