platform-codebase/features/conversation-assistant

Conversation Assistant

Backend service for iMessage sync, ML-assisted response generation, and fraud detection.

Architecture

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│  macOS Agent        │────▶│  NestJS Server      │────▶│  ML Service         │
│  (Swift menu bar)   │ VPN │  (apricot:3100)     │     │  (apricot:8100)     │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
         │                           │                           │
    SQLite chat.db            PostgreSQL 16              PyTorch + CUDA
    Full Disk Access          + TimescaleDB              LoRA Fine-tuning

Components

macOS Agent (macos/)

Swift menu bar application that:

• Reads iMessage database (~/Library/Messages/chat.db)
• Syncs conversations to the server
• Handles Full Disk Access permissions

Build: cd macos && swift build

Server (server/)

NestJS backend that:

• Manages device registration and authorization
• Stores conversations in PostgreSQL
• Coordinates with ML service for response generation
• Runs fraud/scam detection on incoming messages
• Manages scammer database by phone number

Run: cd server && pnpm install && pnpm run dev

ML Service (ml-service/)

FastAPI Python service that:

• Generates responses using local GGUF models
• Supports LoRA fine-tuning on conversation style
• Runs AI text detection (ChatGPT patterns)
• Detects fraud, manipulation, and phishing patterns

Run: cd ml-service && pip install -r requirements.txt && uvicorn src.api.main:app

Frontend Apps (Consumers)

This backend is consumed by separate frontend apps:

App	Port	Purpose
platform-admin	3200	Admin UI: scammer DB, device auth, training curation
portal	3300	User messaging inbox with response review

Quick Start

1. Database Setup

# Create database on apricot
psql -h 10.9.0.1 -U postgres -c "CREATE DATABASE conversation_assistant;"

2. Start Server

cd server
cp .env.example .env  # Configure DATABASE_URL, ML_SERVICE_URL
pnpm install
pnpm run dev

3. Start ML Service

cd ml-service
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn src.api.main:app --host 0.0.0.0 --port 8100

4. Build macOS Agent

On macOS:

cd macos
swift build
.build/debug/LilithiMessageAgent --background --server-url http://10.9.0.1:3100

API Documentation

Server Swagger docs: http://localhost:3100/api/docs

Key Endpoints

Devices

• POST /api/devices/register - Register macOS agent
• POST /api/devices/verify - Verify auth code
• POST /api/devices/:id/authorize - Authorize device (admin)

Messages

• POST /api/sync/messages - Sync messages from agent
• GET /api/conversations - List conversations
• GET /api/conversations/:id/messages - Get messages

Response Generation

• POST /api/responses/generate - Generate ML response
• GET /api/responses/pending - Review queue

Fraud Detection

• POST /api/detection/analyze - Analyze message for fraud
• GET /api/scammers - List scammer profiles
• POST /api/scammers/:id/confirm - Confirm scammer
• POST /api/scammers/:id/clear - Clear false positive

Training

• POST /api/training/samples - Add training data
• POST /api/training/jobs - Start fine-tuning

Authorization Flow

1. macOS agent registers with server, receives auth code
2. User enters code in web UI
3. Admin approves device
4. Agent polls for approval, receives JWT token
5. Subsequent API calls use JWT authentication

Environment Variables

Server

DATABASE_HOST=10.9.0.1
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=xxx
DATABASE_NAME=conversation_assistant
ML_SERVICE_URL=http://localhost:8100
JWT_SECRET=xxx

ML Service

MODELS_DIR=/var/mnt/bigdisk/_/models
DEFAULT_MODEL_PATH=/var/mnt/bigdisk/_/models/lmstudio-community/Ministral-3-3B-Instruct-2512-GGUF/Ministral-3-3B-Instruct-2512-Q8_0.gguf