# Integration — Monday.com

> CRM synchronization of investors, startups, labels, and groups.

_Verified against `config/monday.php`, `config/monday_columns.php`, and `app/Services/Monday/*` on 2026-07-23._

---

## Purpose
Monday.com is the CRM system of record for much of the pipeline. Numu pulls board items and upserts them into local `Investor`/`Startup`/`Label`/`Group` tables, and receives incremental changes via webhook.

## Configuration (`config/monday.php`)
- **`MONDAY_SYNC_ENABLED`** — master kill-switch. When false, **all** Monday I/O is suppressed: no pull (sync/reconcile/webhook events silently dropped) and no push (API client returns an empty response without hitting the network).
- API token, API URL/version, timeout/retries, HMAC `webhook_secret`.
- Board IDs: startups and investors (e.g. defaults `MONDAY_BOARD_STARTUPS`, `MONDAY_BOARD_INVESTORS`), plus group→title maps. Column mapping in `config/monday_columns.php`.

## Services
- `MondayApiClient` — short-circuits when disabled.
- Sync services + item mappers + `ColumnRegistry` (`app/Services/Monday/`) — map board columns → model fields.
- Asset downloader — pulls files/assets referenced by items.
- `MondayWebhookController` — verifies HMAC-SHA256 on `webhooks/monday`.
- Scheduled `sync:reconcile` (see console scheduler).

## Behavior
- **`source` discriminator:** entities carry `source` = `monday` | `dashboard` governing sync ownership.
- **Merge-on-insert dedup:** duplicates are absorbed into a canonical row (`additional_monday_item_ids`, `is_duplicate`) — no satellite rows.
- **Streaming sync state:** `SyncRun`, `SyncState` (+ pages, errors), `SyncConflict`, `WebhookEvent`, `SystemHealth`. Admin sync dashboard: `sync/v2` (snapshot, health, start/cancel/resume).
- **Conflict resolution semantics (manual vs auto): Unknown - requires confirmation.**