Skip to content

Edge Client Integration Documentation

Last Updated: November 14, 2025 Status: Active - Critical updates available

🚨 Start Here: Critical Updates (November 2025)

If you're implementing the edge client, read these first:

🔴 URGENT: WebSocket Connection Fix (November 15, 2025)

If your WebSocket is failing to connect:

  1. WEBSOCKET_QUICK_FIX.md (archived) ⏱️ 2 minutes
  2. CRITICAL: Add Authorization header to WebSocket
  3. Quick code fix

  4. Get connected in 2 minutes

  5. WEBSOCKET_SETUP_GUIDE.md ⏱️ 15 minutes

  6. Complete WebSocket protocol documentation
  7. Message types and examples
  8. Error troubleshooting
  9. Reconnection logic

🟡 HTTP Authentication (November 14, 2025)

  1. EDGE_CLIENT_QUICK_START.md ⏱️ 5 minutes
  2. Critical breaking changes
  3. Authentication requirement
  4. Quick implementation checklist

  5. Action Required: Add Bearer token authentication

  6. EDGE_CLIENT_UPDATES_NOV_2025.md ⏱️ 20 minutes

  7. Complete details on all backend changes
  8. Photo processing integration guide
  9. Rate limiting handling
  10. Migration checklist
  11. Example code updates
  12. Testing instructions

📖 Core Edge Agent Documentation

After reading the critical updates, review these foundational documents:

  1. /docs/edge/EDGE_AGENT_SPEC.md ⏱️ 30 minutes
  2. Edge agent architecture overview
  3. Communication protocol specification
  4. Command and event types
  5. Security considerations

  6. ⚠️ Now includes November 2025 updates banner

  7. /docs/edge/MAC_MINI_IMPLEMENTATION.md ⏱️ 60 minutes

  8. Complete implementation guide
  9. Technology stack recommendations
  10. Phase-by-phase development plan
  11. Code examples
  12. Deployment instructions
  13. ⚠️ Now includes November 2025 updates banner

📋 Implementation Priority

Phase 1: Critical (Week 1) 🔴

Must complete before production:

  1. ✅ Read EDGE_CLIENT_QUICK_START.md
  2. ✅ Add Bearer token authentication
  3. ✅ Test authentication with dev backend
  4. ✅ Add 401 error handling
  5. ✅ Add 429 rate limit handling

Estimated Time: 2-4 hours

Phase 2: Foundation (Week 1-2) 🟡

Core relay functionality:

  1. ✅ Implement iMessage monitoring
  2. ✅ Implement iMessage sending
  3. ✅ Connect to orchestrator endpoint (with auth)
  4. ✅ Handle basic message flow
  5. ✅ Test end-to-end message delivery

Estimated Time: 1-2 weeks

Phase 3: Features (Week 3-4) 🟢

Enhanced capabilities:

  1. ⏳ Photo upload and processing
  2. ⏳ Local message scheduling
  3. ⏳ Message filtering
  4. ⏳ Rule engine

Estimated Time: 2-3 weeks

Phase 4: Production Hardening (Week 5-6) ⚪

Production readiness:

  1. ⏳ HMAC signature validation (when backend activates)
  2. ⏳ Error recovery and retry logic
  3. ⏳ Monitoring and health checks
  4. ⏳ Backup and recovery

Estimated Time: 1-2 weeks

🔑 Environment Configuration

Required Environment Variables:

# Backend connection
BACKEND_URL=https://archety-backend-prod.up.railway.app

# Authentication (CRITICAL - Required for production)
RELAY_WEBHOOK_SECRET=your-shared-secret-here

# User identification
USER_PHONE=+15551234567

# Optional: iMessage configuration
MESSAGES_DB_PATH=~/Library/Messages/chat.db

How to Get RELAY_WEBHOOK_SECRET:

  1. Generate a secret: openssl rand -hex 32
  2. Share with backend engineer to configure on Railway
  3. Add to your edge client .env file

📞 Backend Endpoints Reference

Authentication Required (Bearer Token)

All these endpoints require Authorization: Bearer {RELAY_WEBHOOK_SECRET}:

Endpoint Method Purpose Rate Limit
/orchestrator/message POST Process incoming messages 60/min per user
/orchestrator/heartbeat POST Relay health check 10/min
/photos/upload POST Upload photos for analysis 20/min

Edge Agent Endpoints (HMAC Token)

These use edge agent authentication (different from relay):

Endpoint Method Purpose Rate Limit
/edge/register POST Register edge agent 1/hour
/edge/sync POST Sync commands/events 100/min
/edge/message POST Send filtered messages 100/min
/edge/command/ack POST Acknowledge commands 100/min

🧪 Testing Checklist

Before deploying to production:

  • Authentication works with valid token
  • Authentication fails with invalid token
  • Authentication fails with missing token
  • Rate limiting triggers at 61st message
  • Retry-After header is respected
  • 401 errors are handled gracefully
  • 429 errors are handled gracefully
  • Messages are delivered end-to-end
  • Photo upload works (if implemented)
  • Error logs are clear and actionable

📚 Additional Resources

Backend Documentation

  • API Docs: https://archety-backend-prod.up.railway.app/docs
  • GitHub: https://github.com/rawrjustin/archety
  • Development Log: /CLAUDE.md
  • Supabase Integration: /docs/integration/MAC_MINI_EDGE_CLIENT_SUPABASE.md
  • Deployment Guide: /docs/backend/DEPLOYMENT.md
  • Architecture Overview: /docs/architecture/

🐛 Troubleshooting

Common Issues

401 Unauthorized: 

Cause: RELAY_WEBHOOK_SECRET doesn't match between client and backend
Fix: Verify secret matches on both sides
Test: curl with -H "Authorization: Bearer $SECRET"

429 Too Many Requests: 

Cause: More than 60 messages/minute from same user
Fix: Implement retry logic with Retry-After header
Test: Send 61 messages rapidly

Connection Refused: 

Cause: Backend URL incorrect or backend is down
Fix: Check BACKEND_URL environment variable
Test: curl https://archety-backend-prod.up.railway.app/health

Photo Upload Fails: 

Cause: Missing authentication or invalid file format
Fix: Verify Bearer token and file is valid image
Test: curl with -F file=@photo.jpg

💬 Support

Questions about:

Contact: - Backend Engineer: Engineer 2 - Backend Repository: https://github.com/rawrjustin/archety

📊 Document Status

Document Status Last Updated Action Required
EDGE_CLIENT_QUICK_START.md ✅ Active Nov 14, 2025 READ FIRST
EDGE_CLIENT_UPDATES_NOV_2025.md ✅ Active Nov 14, 2025 IMPLEMENT
EDGE_AGENT_SPEC.md ✅ Updated Nov 14, 2025 Reference
MAC_MINI_IMPLEMENTATION.md ✅ Updated Nov 14, 2025 Guide
MAC_MINI_EDGE_CLIENT_SUPABASE.md ℹ️ Info Earlier Optional

Total Reading Time: ~2 hours Implementation Time: 4-8 weeks (phased) Critical Items: Authentication (2-4 hours)

Last Updated: November 14, 2025 Maintained By: Backend Engineering Team