---
title: "Архітектура Email AI-CRM"
description: "IMAP poll, EmailProcessor, JSONB колекції, SMTP, cron і webhook"
locale: "uk"
---
# Архітектура Email AI-CRM

> **EN canonical:** повна діаграма, індекси JSONB та режими cron/IDLE — [Email AI-CRM architecture (EN)](/docs/architecture/email-ai-crm.md)

## Система

```mermaid
flowchart TB
    subgraph Ingest["Збір"]
        Cron["POST /api/cron/email-processor poll"]
        Webhook["POST /api/webhooks/email/inbound"]
        Idle["EMAIL_PROCESSOR_AUTOSTART опційно"]
    end

    subgraph Core["services/email"]
        EP[EmailProcessor]
        IMAP[ImapListener.pollBatch]
        Parser[EmailParser]
        Sec[SecurityPipeline]
        AI[Intent + Sentiment + Generator]
        CRM[ContactService + TaskService]
        Drafts[EmailDraftService]
    end

    subgraph Persist["features/email-crm JSONB"]
        T[email_threads]
        C[email_contacts]
        M[email_messages]
        D[email_drafts]
        TK[email_tasks]
        U[email_api_usage]
    end

    subgraph Out["Вихід"]
        SMTP[EmailSenderService]
        Notify[EmailNotificationService]
    end

    subgraph Admin["Адмін"]
        API["/api/admin/email/*"]
        UI["admin/crm/*"]
    end

    Cron --> IMAP
    Webhook --> EP
    Idle --> EP
    IMAP --> EP
    EP --> Parser --> Sec --> AI
    AI --> CRM
    AI --> Drafts
    EP --> T
    EP --> C
    EP --> M
    EP --> D
    EP --> TK
    AI --> U
    Drafts --> SMTP
    EP --> Notify
    API --> Persist
    UI --> API
```

## Модулі

| Шлях | Роль |
|------|------|
| `features/email-crm/pipeline/email-processor.ts` | Оркестратор: dedup, poll, ingest |
| `features/email-crm/pipeline/imap/` | `pollBatch()` для cron |
| `features/email-crm/pipeline/smtp/email-sender.ts` | Вихідні відповіді |
| `features/email-crm/repositories/` | JSONB Contact / Task / Draft |
| `features/email-crm/services/` | Thread, message, analytics, send |

## JSONB модель

Рядок платформи: `id`, `data`, `created_at`, `updated_at`.

| Колекція | Id документа |
|----------|--------------|
| `email_threads` | RFC thread root / Message-ID |
| `email_contacts` | `contact_<sha256(email)>` |
| `email_messages` | RFC Message-ID |
| `email_drafts` | `draft_` |
| `email_tasks` | `task_` |
| `email_api_usage` | `req__` |

Міграції: `009_email_crm_jsonb.sql`, `010_email_crm_tasks_jsonb.sql`.

`EMAIL_CRM_PERSISTENCE=memory` — лише dev/tests; інакше Postgres через фабрики сервісів.

## Ідемпотентність

| Механізм | Поведінка |
|----------|-----------|
| DB dedup | `EmailMessageService.exists(messageId)` |
| Poll mutex | Паралельний `pollInboundBatch` → `{ skipped: true }` |
| pollBatch | Чекає всі `handleEmail` перед disconnect |
| Webhook | `uid: 0` — без IMAP mark-seen |

## Cron vs IDLE

| Режим | Коли |
|-------|------|
| **poll** (рекомендовано) | k8s CronJob, serverless |
| **start** | Dedicated Node + `instrumentation.ts` |
| HTTP start | Debug: `EMAIL_PROCESSOR_ALLOW_HTTP_START=true` |

## Безпека

- Cron/webhook: `Bearer $CRON_SECRET` або HMAC `X-Email-Webhook-Signature`.
- Admin API: сесія + `isPlatformAdmin`.
- Inbound: 4 шари anti-injection до LLM.

## Пов’язане

- [Email AI-CRM (функція)](/docs/features/email-ai-crm.md)
- [Email AI-CRM API](/docs/api/email-ai-crm.md)
- [Backend modes](/docs/architecture/backend-modes-and-databases.md)