{"slug":"strategy/product-strategy/ACTION_COMPLETION_ARCHITECTURE","title":"Action Completion Architecture","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/ACTION_COMPLETION_ARCHITECTURE.mdx","bytes":11510,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> How actions flow from insight to execution in IntegrateWise.\n> Canonical reference for agents working on the HITL/approval/execution layer.\n> Last updated: April 12, 2026\n\n---\n\n## Design Principle\n\nThe workspace (L1) is the daily driver. Users manage accounts, track tasks, run workflows here.\nThe cognitive layer (L2) accelerates what they're already doing — surfaces the right action at the right time.\n\n**Demo story**: \"Here are your at-risk accounts. Click. See why. Approve the action. Done.\"\n\nThe product is NOT \"look what our AI can do.\" It IS \"this is your workspace. The AI makes you faster.\"\n\n---\n\n## The Action Pipeline\n\n```\nSignal → Think → Propose → Govern → HITL → Act → Learn → Repeat\n```\n\n| Stage       | Service       | What happens                                                           |\n| ----------- | ------------- | ---------------------------------------------------------------------- |\n| **Signal**  | Think         | External data triggers a signal rule (e.g., health score < 60)         |\n| **Think**   | Think         | Signal engine escalates → creates ProposedAction                       |\n| **Propose** | Think (Queue) | Queue handler persists action to `actions` table as `pending_approval` |\n| **Govern**  | Govern        | Policy check — can this action execute? RBAC, guardrails               |\n| **HITL**    | Workflow      | Human reviews in PendingApprovalsCard → ApprovalModal                  |\n| **Act**     | Act           | Mandatory approval token + governance double-check → execute           |\n| **Learn**   | Think         | Outcome feedback → decision_memory → pattern extraction                |\n\n---\n\n## Two HITL Paths\n\n### 1. Spine DB-based (primary — production flow)\n\n- `GET /api/v1/cognitive/hitl/queue` → reads `actions` table where `status = 'pending_approval'`\n- `POST /api/v1/cognitive/hitl/queue` → approve/deny, writes to `actions`, sends to `ACT_QUEUE` on approve, writes to `decision_memory` on deny\n- `GET /api/v1/cognitive/hitl/history` → reads approved/denied actions\n\n### 2. Durable Object-based (signal-level, real-time)\n\n- `POST /hitl/create` → creates pending HITL record in DO storage\n- `POST /hitl/resolve` → if approved, generates approval_token, calls Act directly\n- `GET /hitl/count` → pending count for badges\n\n---\n\n## Where Actions Surface (L1 Workspace)\n\nActions are NOT a separate feature — they're embedded in the views users already use daily.\n\n| Surface                       | Component                                  | Data Source                                       |\n| ----------------------------- | ------------------------------------------ | ------------------------------------------------- |\n| **CS Today View**             | PendingApprovalsCard + ExecutionStatusCard | `useL2Recommendations(CUSTOMER_SUCCESS)`          |\n| **CS At-Risk View**           | PendingApprovalsCard + ApprovalModal       | `useL2Recommendations(CUSTOMER_SUCCESS, at-risk)` |\n| **BizOps Dashboard**          | PendingApprovalsCard                       | `useL2Recommendations(BIZOPS)`                    |\n| **Twin Chat (inline)**        | Quick Action Buttons + ActionDraftCard     | `cognitive.twinAct()` API                         |\n| **L2 Drawer (ActSurface)**    | Approve/Reject buttons                     | `getHITLQueue()` from l2-client                   |\n| **RevOps Pending Review**     | PendingApprovalsCard + ApprovalModal       | `useL2Recommendations(REVOPS)`                    |\n| **Finance Invoice Approvals** | Domain-specific approval UI                | Local state (needs wiring)                        |\n| **Admin Approval Workflows**  | RBAC approval system                       | Mock data (needs wiring)                          |\n\n---\n\n## Twin Chat — Action Trigger Flow\n\nThe Twin Chat is the demo closer. The flow:\n\n1. User asks Twin about an at-risk account (entity-scoped via `entityId` prop)\n2. Twin responds with grounded analysis from Entity 360\n3. **Quick Action Buttons** appear below the response (domain-contextual)\n4. User clicks \"Schedule Health Call\" → calls `POST /api/v1/cognitive/twin/act` with `draft_only: true`\n5. **ActionDraftCard** shows suggested summary + next steps\n6. User clicks \"Approve & Execute\" → calls with `draft_only: false`\n7. Goes through Govern check → Act execution → outcome learning\n\n### Domain Actions\n\n| Domain | Action Key               | Label                  | Description                            |\n| ------ | ------------------------ | ---------------------- | -------------------------------------- |\n| CS     | `schedule_health_call`   | Schedule Health Call   | Book check-in with primary stakeholder |\n| CS     | `draft_retention_email`  | Draft Retention Email  | AI-drafted email from risk signals     |\n| CS     | `escalate_to_leadership` | Escalate to Leadership | Flag for executive attention           |\n| BizOps | `create_task`            | Create Task            | Turn insight into actionable task      |\n| BizOps | `trigger_workflow`       | Trigger Workflow       | Start automated workflow               |\n| BizOps | `send_payment_reminder`  | Send Payment Reminder  | Draft payment follow-up                |\n\n---\n\n## Frontend Component Inventory\n\n### Reusable Components (`apps/web/src/components/l2/approvals/`)\n\n| Component              | File                         | Purpose                                                                        |\n| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------ |\n| `PendingApprovalsCard` | `pending-approvals-card.tsx` | Card queue of pending approvals. Accepts `approvals` prop (PendingApproval[]). |\n| `ApprovalModal`        | `approval-modal.tsx`         | Full-screen approval view with evidence, urgency, confidence, entity info.     |\n| `ExecutionStatusCard`  | `execution-status-card.tsx`  | Running/completed/failed execution tracker with live timer.                    |\n| `ActionBar`            | `action-bar.tsx`             | Inline action card with policy requirements and risk level.                    |\n| `approvalsApi`         | `approvals-api.ts`           | Typed API client for HITL queue. All decisions route through Workflow.         |\n\n### Hooks\n\n| Hook                   | File               | Purpose                                        |\n| ---------------------- | ------------------ | ---------------------------------------------- |\n| `useL2Recommendations` | `hooks/use-l2.ts`  | Fetches pending recommendations (30s stale).   |\n| `useL2Decide`          | `hooks/use-l2.ts`  | Mutation: approve/reject, invalidates queries. |\n| `useHITLQueue`         | `hooks/use-api.ts` | Polls HITL queue every 15s.                    |\n| `useHITLAction`        | `hooks/use-api.ts` | Mutation for HITL approve/deny.                |\n\n### API Client Methods\n\n| Method                   | File                | Endpoint                             | Purpose                            |\n| ------------------------ | ------------------- | ------------------------------------ | ---------------------------------- |\n| `cognitive.twinAct()`    | `lib/api-client.ts` | `POST /api/v1/cognitive/twin/act`    | Draft or execute action from Twin. |\n| `cognitive.hitlQueue()`  | `lib/api-client.ts` | `GET /api/v1/cognitive/hitl/queue`   | Fetch pending proposals.           |\n| `cognitive.hitlAction()` | `lib/api-client.ts` | `POST /api/v1/cognitive/hitl/queue`  | Approve/deny/request changes.      |\n| `cognitive.act()`        | `lib/api-client.ts` | `POST /api/v1/cognitive/act/execute` | Execute with approval token.       |\n\n---\n\n## Database Tables\n\n| Table               | Purpose                                  | Key Columns                                                                     |\n| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |\n| `actions`           | Primary action queue                     | status (pending_approval/approved/denied/executed), approval_token, target_tool |\n| `action_proposals`  | L2→L1 approval flow                      | status (pending/approved/rejected/executed/failed), trust_score, evidence_refs  |\n| `decisions`         | Cognitive Brain decisions                | reasoning_chain, evidence_snapshot, trust_score                                 |\n| `decision_memory`   | Organizational learning                  | was_correct, pattern_tags, reusability_score                                    |\n| `decision_patterns` | Reusable patterns                        | success_rate, recommended_action_type                                           |\n| `v_today_queue`     | VIEW: tasks + signals + action_proposals | UNION ALL of pending items                                                      |\n\n---\n\n## Backend Services\n\n| Service                             | Endpoints                                                                  | Role                                     |\n| ----------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------- |\n| **Think** (`services/think/`)       | `POST /v1/twin/act`, `POST /v1/outcome/feedback`, `POST /v1/decide`        | Propose actions, receive outcomes, learn |\n| **Govern** (`services/govern/`)     | `POST /v1/check`, `POST /v1/approve`, `POST /v1/reject`, `GET /v1/pending` | Policy gate                              |\n| **Act** (`services/act/`)           | `POST /execute`, `GET /proposals/:situation_id`                            | Execute with mandatory approval token    |\n| **Workflow** (`services/workflow/`) | `GET/POST /api/v1/cognitive/hitl/queue`, HITL DO                           | Orchestrate approval queue               |\n\n---\n\n## Rules (KT Notes)\n\n1. **No action executes without an approval token** — Act service returns 403 without `x-approval-token`\n2. **Governance is mandatory** — even with valid token, Act calls Govern for double-check\n3. **Fail-safe on governance unavailability** — if Govern is down, execution is blocked (not allowed)\n4. **Results re-ingest through pipeline** — Act does NOT write directly to Spine\n5. **Deny writes learning signal** — rejection feeds back to Think via `decision_memory` so AI adjusts\n6. **Frontend routes ALL decisions through Workflow HITL queue** — never call Act/Govern directly\n\n---\n\n## What's Wired vs. Needs Wiring\n\n| Component                         | Status                        |\n| --------------------------------- | ----------------------------- |\n| CS Today View approval queue      | Wired to useL2Recommendations |\n| CS At-Risk View                   | Fully wired                   |\n| BizOps Dashboard approval queue   | Wired to useL2Recommendations |\n| Twin Chat quick actions           | Wired to cognitive.twinAct()  |\n| Twin Chat entity scoping          | Wired (entityId prop)         |\n| L2 Drawer ActSurface              | Wired to getHITLQueue         |\n| RevOps Pending Review             | Fully wired                   |\n| Finance Invoice Approvals         | NOT wired (client-side only)  |\n| Admin Approval Workflows          | NOT wired (mock data)         |\n| ExecutionStatusCard live data     | Needs Act execution stream    |\n| Flow C write-back after Twin Chat | Not triggered yet             |\n"}