Deep Work Notifier

Eliminate FOMO, reclaim your focus. A smart notification system that only interrupts your deep work when it truly matters.

You're 45 minutes into a flow state. Code is flowing. Then the thought hits: "What if a server is down? What if a client is trying to reach me?"

You check your phone. 23 notifications. None of them mattered. But your flow is gone.

The average knowledge worker checks messaging apps every 6 minutes. That's 80 interruptions per day. Deep work becomes impossible.

Deep Work Notifier creates a trusted filter between the chaos of incoming messages and your attention:

• API Endpoint for critical alerts (fonio.ai call notifications, monitoring alerts)
• AI-Powered WhatsApp filtering — only urgent messages interrupt you
• Everything else waits until you're ready

Your phone stays silent. Your focus stays protected. But when a server crashes or a client has an emergency, you know immediately.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Incoming       │     │  Deep Work       │     │  You (Focused)  │
│  Messages       │────→│  Notifier        │────→│  Only when      │
│                 │     │  (Smart Filter)  │     │  truly urgent   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │
        ├── fonio.ai calls → INSTANT notification
        ├── Server down alerts → INSTANT notification
        └── WhatsApp messages → AI checks importance → Maybe notify

1. Server Monitoring — Get notified immediately when infrastructure fails
2. Client Escalations — Know when a client messages "everything is down"
3. Call Notifications — fonio.ai or similar services can trigger instant alerts
4. Team Emergencies — Only messages marked urgent by your team
5. Everything else — Silent. No interruptions.

The project includes a justfile for easy command execution. Install just if you haven't already:

# macOS
brew install just

# Or visit: https://github.com/casey/just

# Clone and enter the project
cd deep-work-notifier

# Run complete setup (creates .env, runs migrations)
just setup

# Edit .env with your settings
vim .env  # or your preferred editor

# Start all services (Docker infrastructure + native notifier)
just start

# Check status
just status

# Send a test notification
just notify "🚨 Server Down" "Production API returning 502 errors" urgent

# Check API health
just health

You should see a macOS notification immediately!

See the justfile for all available commands.

Monitor WhatsApp messages and let AI decide what deserves your attention:

# Add to .env:
# AZURE_OPENAI_ENDPOINT=...
# AZURE_OPENAI_API_KEY=...
# AZURE_OPENAI_DEPLOYMENT_ID=gpt-4
# WHATSAPP_NUMBERS=your-number

# Run the WhatsApp reader
cargo run -p whatsapp-reader

Scan the QR code with WhatsApp on your phone. The AI will now:

• ✅ Notify you for: "Server is down!", "Urgent: need your approval", "Client escalation"
• ❌ Ignore: "Hey", "LOL", "Check out this meme", "Good morning team"

Configure fonio.ai to send webhooks to your Deep Work Notifier:

# When someone calls your fonio.ai number
curl -X POST http://localhost:8080/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "title": "📞 Incoming Call",
    "message": "Call from +1-234-567-8900",
    "category": "info"
  }'

# When a monitor fails
curl -X POST http://localhost:8080/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "title": "🔥 $SERVICE_NAME Down",
    "message": "$MSG",
    "category": "urgent"
  }'

curl -X POST http://localhost:8080/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "title": "⚠️ HIGH: Database Connection Pool Exhausted",
    "message": "Connection pool at 95% capacity for 5 minutes",
    "category": "warning"
  }'

Docker containers cannot display native macOS notifications. They run in isolated sessions without access to the host's WindowServer and Notification Center.

Solution:

• Backend + PostgreSQL: Containerized in Docker
• Notifier: Runs natively on macOS host
• WhatsApp Reader: Run natively for QR code scanning

This gives you the best of both worlds: reproducible infrastructure + working notifications.

deep-work-notifier/
├── apps/
│   ├── backend/          # Actix-web API (REST endpoint)
│   ├── notifier/         # Native macOS notification listener
│   └── whatsapp-reader/  # WhatsApp + Azure OpenAI filtering
├── packages/
│   ├── models/           # Shared SeaORM entities
│   └── migration/        # Database migrations
├── docker-compose.yml
└── Cargo.toml

Create .env:

# Database
DATABASE_URL=postgres://notifier:notifier@localhost:5432/notifications

# Backend
BIND_ADDR=0.0.0.0:8080
RUST_LOG=info

# Azure OpenAI (for WhatsApp AI filtering)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_DEPLOYMENT_ID=gpt-4
AZURE_OPENAI_API_VERSION=2024-02-01

# WhatsApp (comma-separated numbers)
WHATSAPP_NUMBERS=+1234567890

# AI threshold (0.0-1.0). Higher = more selective
IMPORTANCE_THRESHOLD=0.7

The just command runner provides simple, memorable commands:

# Start everything (Docker + native notifier)
just start

# Check status of all services
just status

# View notifier logs
just notifier-logs

# Stop everything
just stop

Terminal 1 — Infrastructure:

docker compose up -d

Terminal 2 — Notification listener (required for macOS notifications):

cargo run -p notifier

Terminal 3 — WhatsApp reader (optional):

cargo run -p whatsapp-reader

For a production setup where the notifier runs 24/7 and auto-starts on login:

# Using just
just notifier-install

# Or manually
./scripts/install-macos-service.sh

# Check if it's running
just status

# View logs
just notifier-logs

This installs the notifier as a system service that:

• ✅ Starts automatically when you log in
• ✅ Restarts if it crashes
• ✅ Runs in the background (no terminal needed)

See scripts/README.md for more details.

For servers without notification needs:

docker compose --profile docker-notifier up -d

Notifications will be logged but not displayed.

For notifications to appear:

1. Install terminal-notifier (recommended):

   brew install terminal-notifier

2. Or enable Script Editor notifications:

   • System Settings → Notifications → Script Editor → Allow

When you need uninterrupted focus:

# Stop WhatsApp reader (silences AI-filtered messages)
# Keep notifier running for critical API alerts only

# Or filter by category in your API calls
# Only send "urgent" and "error" to the API during deep work

POST /api/notifications
Content-Type: application/json

{
  "title": "string (required)",
  "message": "string (required)",
  "category": "urgent|error|warning|info|success"
}

GET /api/notifications

GET /health

The WhatsApp reader uses Azure OpenAI GPT-4 to analyze each incoming message:

Message: "Hey, can you check the server?"
AI Analysis: This is a request about server status. Importance: HIGH
→ Send notification

Message: "lol that's funny"
AI Analysis: This is casual conversation. Importance: LOW
→ Silently log, no notification

The AI considers:

• Keywords: "down", "error", "urgent", "broken", "ASAP"
• Context: Work-related vs. personal
• Sender: Known contacts vs. unknown
• Tone: Frustrated/urgent vs. casual/friendly

You control sensitivity with IMPORTANCE_THRESHOLD:

• 0.9 — Only true emergencies
• 0.7 — Work-critical messages (default)
• 0.5 — Include important but not urgent

1. Ensure notifier is running natively: cargo run -p notifier
2. Enable Script Editor in System Settings → Notifications
3. Install terminal-notifier: brew install terminal-notifier

Run natively, not in Docker:

cargo run -p whatsapp-reader

# Check PostgreSQL is running
docker compose ps

# Check logs
docker compose logs postgres

1. API receives POST /api/notifications
2. SeaORM inserts into PostgreSQL
3. Database trigger fires NOTIFY
4. Native notifier receives via LISTEN
5. macOS notification displayed

No polling. Instant delivery. Minimal resource usage.

• No phone checking — Your phone stays silent, no FOMO
• Trusted filter — AI or API decides what's urgent
• Zero distraction — Only interruptions that matter
• Local first — Your data stays on your machine
• Simple — No cloud services, no subscriptions

The repository includes a GitHub Actions workflow (.github/workflows/docker.yml) that automatically builds and publishes Docker images to GitHub Container Registry (GHCR).

# Tag a release
git tag v1.0.0
git push origin v1.0.0

This will:

1. Build multi-platform images (linux/amd64, linux/arm64)
2. Push to ghcr.io/yourusername/deep-work-notifier/
3. Create a GitHub Release with notes

# Use specific version in docker-compose.yml
export IMAGE_TAG=v1.0.0
docker compose up -d

Or pull directly:

docker pull ghcr.io/yourusername/deep-work-notifier/backend:v1.0.0

See scripts/README.md for complete DevOps documentation.

MIT — Use it, modify it, reclaim your focus.

"Every notification is someone else's priority, not yours." — Except when it's actually yours. Deep Work Notifier knows the difference.