# @messenger — iMessage Sync Ecosystem

Standalone iMessage sync platform: macOS agent reads the local iMessage DB, syncs to a NestJS backend, and exposes data via MCP for Claude Code.

---

## Applications

### imessage-sync — NestJS Sync API

Receives messages from macOS, stores and processes them. Pure data sync — no ML hooks.

```
imessage-sync/
├── backend/           NestJS API (port 3100)
│   ├── src/
│   │   ├── entities/          device, contact, conversation, message
│   │   ├── modules/
│   │   │   ├── devices/       Device registration + JWT auth
│   │   │   ├── sync/          Message + Contact sync endpoints
│   │   │   └── processing/    Text extraction, attachment saving (NO ML)
│   │   ├── migrations/        Sync-only schema (4 tables)
│   │   ├── health.controller.ts
│   │   ├── app.module.ts
│   │   ├── main.ts
│   │   └── data-source.ts     TypeORM CLI data source
│   ├── .swcrc                 ESM output (type: es6, resolveFully: true)
│   └── package.json           @lilith/imessage-sync-backend
├── shared/            Shared types (re-exports from @lilith/types)
└── docker-compose.yml PostgreSQL (25433) + Redis (26380)
```

**Key decisions:**
- ProcessingService stripped of: embedding queue POST, ScreeningService trigger
- All entity `@Column` decorators have explicit `type:` for SWC compatibility
- `migrationsRun: true` — app runs migrations on boot

**Commands:**
```bash
cd imessage-sync
docker compose up -d                    # Start PostgreSQL + Redis
cd backend && bun run build             # Build (SWC, ~250ms)
cd backend && bun run start:prod        # Start (port 3100)
cd backend && bun run typecheck         # Typecheck (0 errors)
```

**Health:** `GET http://localhost:3100/health`
**Swagger:** `http://localhost:3100/api/docs`

### imessage-macos — Swift macOS Menu Bar Agent

Reads iMessage database locally, syncs messages to the imessage-sync backend.

```
imessage-macos/
├── Package.swift              Swift package (iMessageMacos)
├── Sources/
│   ├── iMessageMacosApp.swift Main app struct + AppDelegate
│   ├── AppVersion.swift       Generated from VERSION.json
│   ├── Models/
│   │   └── ActivityLog.swift
│   └── Services/
│       ├── APIClient.swift    HTTP client + Keychain + payload types
│       ├── SyncManager.swift  Periodic sync orchestrator
│       ├── iMessageReader.swift  GRDB-based SQLite reader
│       ├── LocalWebServer.swift  Local web UI server
│       └── SendService.swift
├── Makefile                   Build/lint/install targets
├── install.sh                 Full installer (build + app bundle + LaunchAgent)
├── uninstall.sh               Full uninstaller
├── deploy-remote.sh           SSH deploy to remote Mac
├── generate-version.sh        AppVersion.swift generator
├── INSTALL.md                 Installation guide
├── .swiftlint.yml             Lint config
└── iMessageMacos.entitlements Contacts, network, keychain access
```

**Bundle ID:** `com.lilith.imessage-macos`
**Keychain service:** `com.lilith.imessage-macos`
**App bundle:** `~/Applications/iMessageMacos.app`
**Logs:** `~/Library/Application Support/iMessageMacos/`

### imessage-mcp — MCP Server for Claude Code

Read-only access to the sync database via Model Context Protocol.

```
imessage-mcp/
├── src/
│   ├── index.ts               MCP server (name: "imessage-mcp")
│   ├── db.ts                  PostgreSQL connection pool
│   ├── formatters.ts          Message/conversation display formatting
│   └── tools/
│       ├── list-conversations.ts
│       ├── get-conversation.ts
│       ├── get-contact.ts
│       ├── search-messages.ts
│       └── get-conversation-stats.ts
├── tsup.config.ts             Bundles to single ESM file
├── tsconfig.json              Path mappings for MCP SDK subpath imports
└── package.json               @lilith/imessage-mcp
```

**MCP config** (`.mcp.json`):
```json
"imessage": {
  "command": "node",
  "args": ["~/Code/@applications/@messenger/imessage-mcp/dist/index.js"],
  "env": {
    "DATABASE_URL": "postgresql://postgres:devpassword@10.0.0.11:25432/messenger"

  }
}
```

**Symlink:** `~/Code/@packages/@ts/@mcp/imessage-mcp` → this directory

**Tools exposed:** `mcp__imessage__list_conversations`, `mcp__imessage__get_conversation`, `mcp__imessage__get_contact`, `mcp__imessage__search_messages`, `mcp__imessage__get_conversation_stats`

**Build:** `bun run build` (tsup, ~30ms)

---

## Infrastructure

| Service    | Port  | Container                     |
|------------|-------|-------------------------------|
| PostgreSQL | 25432 | production (black)            |
| PostgreSQL | 25433 | local dev (docker-compose)    |
| Redis      | 26380 | lilith-imessage-sync-redis    |

**DB:** `messenger` (was `imessage_sync`) / user: `postgres` / pass: `devpassword`

**Tables:** devices, contacts, conversations, messages (+ migrations)

---

## Remaining Work

- [ ] **Delete old MCP package**: `~/Code/@packages/@ts/@mcp/mcp-conversation-viewer/` is superseded by imessage-mcp
- [ ] **macOS agent testing**: Swift agent renamed to iMessageMacos, not yet tested against new backend
- [ ] **Production deployment**: Docker Compose is dev-only; needs production config for VPS
- [x] **Production DB rename**: Done — `messenger` on black (25432) and local dev (25433)