Email AI-CRM architecture

System diagram

Schema-only tables (001 — not wired)

Related documentation

Email AI-CRM architecture

System diagram

Schema-only tables (001 — not wired)

Related documentation

Email AI-CRM architecture

System diagram

Schema-only tables (001 — not wired)

Related documentation

Persistence — types + jsonb-collection → db()

CRM repositories and services never call raw SQL. Types are split into features/email-crm/types/{contact,task,draft}.ts so repositories can import type without pulling service factories into a CJS require cycle.

Active JSONB collections

Migrations: 009_email_crm_jsonb.sql + 010_email_crm_tasks_jsonb.sql.

Idempotency and concurrency

1. DB dedup — EmailMessageService.exists(messageId) at start of handleEmail.
2. Poll mutex — overlapping pollInboundBatch returns { skipped: true }.
3. Await handlers — pollBatch waits for all handleEmail promises before disconnect.
4. Webhook — uid === 0 skips IMAP markAsSeen.

Cron vs IDLE

Security

• Cron/webhook: fail-closed Bearer $CRON_SECRET or HMAC X-Email-Webhook-Signature.
• Admin API: session + isPlatformAdmin.
• Inbound: 4-layer injection pipeline before any LLM call.
• Outbound: output validation on generated replies; CRM SMTP credentials required at send time.

Same-workflow: orders desk under CrmAdminShell.

Persistence — types + jsonb-collection → db()

CRM repositories and services never call raw SQL. Types are split into features/email-crm/types/{contact,task,draft}.ts so repositories can import type without pulling service factories into a CJS require cycle.

Active JSONB collections

Migrations: 009_email_crm_jsonb.sql + 010_email_crm_tasks_jsonb.sql.

Idempotency and concurrency

1. DB dedup — EmailMessageService.exists(messageId) at start of handleEmail.
2. Poll mutex — overlapping pollInboundBatch returns { skipped: true }.
3. Await handlers — pollBatch waits for all handleEmail promises before disconnect.
4. Webhook — uid === 0 skips IMAP markAsSeen.

Cron vs IDLE

Security

• Cron/webhook: fail-closed Bearer $CRON_SECRET or HMAC X-Email-Webhook-Signature.
• Admin API: session + isPlatformAdmin.
• Inbound: 4-layer injection pipeline before any LLM call.
• Outbound: output validation on generated replies; CRM SMTP credentials required at send time.

Same-workflow: orders desk under CrmAdminShell.

Persistence — types + jsonb-collection → db()

CRM repositories and services never call raw SQL. Types are split into features/email-crm/types/{contact,task,draft}.ts so repositories can import type without pulling service factories into a CJS require cycle.

Active JSONB collections

Migrations: 009_email_crm_jsonb.sql + 010_email_crm_tasks_jsonb.sql.

Idempotency and concurrency

1. DB dedup — EmailMessageService.exists(messageId) at start of handleEmail.
2. Poll mutex — overlapping pollInboundBatch returns { skipped: true }.
3. Await handlers — pollBatch waits for all handleEmail promises before disconnect.
4. Webhook — uid === 0 skips IMAP markAsSeen.

Cron vs IDLE

Security

• Cron/webhook: fail-closed Bearer $CRON_SECRET or HMAC X-Email-Webhook-Signature.
• Admin API: session + isPlatformAdmin.
• Inbound: 4-layer injection pipeline before any LLM call.
• Outbound: output validation on generated replies; CRM SMTP credentials required at send time.

Same-workflow: orders desk under CrmAdminShell.