# Business Domain — Investors

> The Investor subject entity, its classification, and its workflows.

_Verified against `app/Models/Investor.php`, routes, and services on 2026-07-23._

---

## Entity
`Investor` (`app/Models/Investor.php`) — uses `SoftDeletes`.

- **Classification (LabelOption FKs, ~15):** averageTicket, category, action, statusOption, referralSource, background, investmentExperience, activityInNumu, and more.
- **Relationships:** belongs to `Country`, `City`, `Group`; hasMany `InvestorSector`, `InvestorStage`, `InvestorMethod` (payment methods); belongsToMany `Tag` (pivot `investor_tags`); morphMany `File`, `Meeting` (as `meetingable`), `EntityNote` (as `notable`). Note bodies are capped at 5000 characters (`EntityNote::BODY_MAX_LENGTH`) across all write paths — see [`../06-history/decisions-log.md`](../06-history/decisions-log.md) (DR-009). Notes may be deleted from the **admin dashboard** only; the AI/API/MCP surface is create/edit-only (DR-010). Admin deletions are hard deletes but audited before removal (DR-011).
- **Bilingual naming:** `full_name_ar/en`, `first_name_ar/en`. Legacy single `name` column is being phased out — see [`../06-history/deprecated.md`](../06-history/deprecated.md).
- **Provenance & dedup:** `source` = `monday` | `dashboard`; merge-on-insert dedup via `is_duplicate`, `additional_monday_item_ids`, `is_favorite`.

> Note: `investment_experience_option_id` vs `investment_experience_level_option_id` — intentional duplication per model docblock; **which is canonical for reporting is Unknown - requires confirmation.**

## Pipeline & actions
- **Groups** represent pipeline stages (New, Pipeline, Pool, Archive, Rejected, …). An investor is in exactly one group.
- Applying an **`action` LabelOption** runs `InvestorLabelActionService` (`app/Services/Actions/`), which may **move group**, **fire notifications**, and **cancel meetings** as configured on the option. This is the single canonical transition path (dashboard, API, MCP, agents all use it).

## Workflows
- **Onboarding:** public `investor_signup` → creates a `dashboard`-source Investor (default group New, action New) → optional scheduling step → onboarding automations fire after a configurable wait window.
- **Back-office management:** filter/search, inline label-section edits, group assignment, tags, notes, favorites.
- **Self-service booking:** OTP-gated meeting creation (see [`meetings.md`](meetings.md)).
- **Committees / Demos:** investors are attendees/evaluators (see committee & demo behavior in [`meetings.md`](meetings.md) and terminology).

## API surface
`/api/v1/investors` (REST mirror of admin filters) and MCP read/full tools (`investor_list/search/get/find_gaps/update/bulk_update`, `investor_set_preferences`, `investor_meetings`, …). See [`../03-ai-agents/tools.md`](../03-ai-agents/tools.md).