messenger/docs/setup/backend.md

Backend Setup

The NestJS backend handles message sync from all providers and stores data in PostgreSQL.

Environment Variables

Create .env in imessage-sync/backend/:

# PostgreSQL
DATABASE_HOST=10.0.0.11
DATABASE_PORT=25432
DATABASE_USER=postgres
DATABASE_PASSWORD=devpassword
DATABASE_NAME=imessage_sync

# Service
PORT=3100
NODE_ENV=development

# Migrations (auto-run on startup, set to 'false' to disable)
MIGRATIONS_RUN=true

Provider Configuration

Each provider is optional — if its credentials aren't set, it logs a warning and skips sync.

Provider	Required Env Var	Setup Guide
iMessage	(push-based from macOS agent)	Built-in
iCloud Mail	ICLOUD_IMAP_USER	icloud-mail.md
Proton Mail	PROTON_IMAP_USER	protonmail.md

Running

cd imessage-sync/backend
pnpm install
pnpm start:dev    # development with hot reload
pnpm start:prod   # production

Database

The backend uses TypeORM with manual migrations. Migrations auto-run on startup unless MIGRATIONS_RUN=false.

Schema Overview

Table	Purpose
devices	Registered macOS agents
contacts	Unified contacts across providers
conversations	Chat threads with provider discriminator
messages	All messages with provider discriminator
email_folders	IMAP folders (iCloud, Proton Mail)
message_folders	Message-to-folder mapping (junction)
pending_messages	Outbound message queue

Key Columns

• conversations.provider / messages.provider — 'imessage', 'protonmail', or 'icloud'
• conversations.external_id — iMessage chat ID or email thread ID
• messages.external_id — iMessage GUID or email Message-ID
• contacts.provider_identifiers — JSONB with per-provider identifiers