# Data Flow

> The main runtime flows through the system.

_Verified against the codebase on 2026-07-23._

---

## 1. Monday.com sync
Pull board items → map via `ColumnRegistry` / item mappers (`app/Services/Monday/`) → upsert Investors/Startups/Labels/Groups with **merge-on-insert** dedup → stream progress into `SyncState` (+ pages/errors) → track `SyncConflict`. Inbound `webhooks/monday` (HMAC-verified) applies incremental changes. Master kill-switch `MONDAY_SYNC_ENABLED` short-circuits all Monday I/O.

## 2. Self-service meeting booking
Subject enters phone/email → **OTP** send/resend/verify (throttled) → availability computed from Microsoft Bookings → `Meeting` created → Bookings **webhook** keeps status/times in sync. Applying a rejection `action` can auto-cancel the subject's meetings (`CancelSubjectMeetingsOnLabelAction`).

## 3. Notification dispatch
Three sources — **Automations**, **LabelOption actions**, **AdminNotification broadcasts** — all implement `ProvidesNotificationChannels` → shared channel manager (email / SMS / WhatsApp / push / in-app) → provider send → **`NotificationLog`** row per attempt with a retry ladder and provider-webhook status (`sent → delivered → read` / `undelivered` / `failed`). Idempotency via `event_id` (groups a multi-channel send) and `idempotency_key` = `entity:recipient:channel:message_type`.

## 4. Managed-agent action (locked model)
`Make.com` triggers a run → **Runtime** loads immutable knowledge package and produces a **proposal only** → `AgentDecisionService`: idempotency → freeze → runtime pause gate → policy resolve (`always_allow` / `needs_approval` / `blocked`) → on approval, **Numu executes** via `AgentActionExecutor` → canonical action service → audit. Make orchestrates/reasons; **Numu executes** (see [`ai-architecture.md`](ai-architecture.md)).

## 5. AI enrichment
`EnrichmentEngine`: provider fetch (Proxycurl/Hunter/WebFetch/Gravatar) → normalize → source resolution → aggregated confidence → `ConfidencePolicy` (≥ 0.80) → write controller → audit → rollback. Bulk runs execute as `AiTask`s (`StartAiTaskJob → ProcessAiTaskItemJob → FinalizeAiTaskJob`).

## 6. MCP tool call (Flow A)
Claude → `/api/v1/ai/mcp/{read|full}` (JSON-RPC, SSE-aware) → `McpAuth:{read|full}` (OAuth 2.1 or Sanctum, tier enforced by URL) → `McpToolRegistry` handler builds a sub-request → **delegates to the existing REST controller** (single source of truth) → response.