Architecture & Concepts

Overview

The device connection system uses a cloud-first architecture where devices connect to the cloud, not the other way around. This means no IP addresses are needed and no firewall configuration is required.

How It Works

✅ Correct Architecture

Your Device (Home/Office)
   ↓ Connects to cloud via HTTPS
Cloud Server (Sulala.ai)
   ↓ Stores search requests
Your Device (Polls for requests)
   ↓ Executes search locally
   ↓ Sends results back
Cloud Server
   ↓ Returns results
You (Anywhere in the world)

Key Points:

• ✅ Device connects to cloud (outbound connection)
• ✅ No firewall/NAT issues
• ✅ No IP addresses needed
• ✅ Works from anywhere
• ✅ Secure (HTTPS + API keys)

❌ Wrong Architecture (What We DON'T Need)

Cloud Server
   ↓ Tries to connect to device IP
Your Device (Home)
   ❌ Firewall blocks
   ❌ NAT issues
   ❌ IP changes
   ❌ Doesn't work

Complete Flow: Remote File Search

Step 1: Device Registration

1. User registers device in dashboard → Gets API key
2. Device agent installed on device
3. Device connects to cloud using API key

Step 2: Device Stays Online

Device Agent
   ↓ Every 30 seconds
POST /api/devices/heartbeat
   ↓ Updates "lastSeenAt"
Cloud marks device as "online"

Step 3: User Initiates Search (From Anywhere)

You (on phone/laptop anywhere)
   ↓ Types "resume.pdf"
   ↓ Clicks "Search"
POST /api/devices/search/query
   ↓ Creates pending search query
   ↓ Status: "pending"
Cloud stores request

Step 4: Device Polls for Searches

Device Agent
   ↓ Every 30 seconds (after heartbeat)
GET /api/devices/search/pending
   ↓ Returns pending searches
   ↓ Finds "resume.pdf" query
Device executes local search

Step 5: Device Reports Results

Device Agent
   ↓ Searches local filesystem
   ↓ Finds: /Users/sai/Documents/resume.pdf
POST /api/devices/search
   ↓ Reports results
   ↓ Updates query status: "completed"
Cloud stores results

Step 6: User Gets Results

You (on phone/laptop)
   ↓ Polls or refreshes
GET /api/devices/search/query?queryId=...
   ↓ Returns results
   ↓ Shows: /Users/sai/Documents/resume.pdf

Why This Architecture Works

1. Outbound Connections Only

• Device makes outbound HTTPS connections
• No inbound firewall rules needed
• Works behind NAT/routers
• Works on any network

2. No IP Addresses

• Device connects to cloud domain (e.g., sulala.ai)
• Cloud doesn't need device IP
• Device identity = API key
• Works even if IP changes

3. Polling Pattern

• Device polls every 30 seconds
• Checks for pending searches
• Executes and reports back
• Simple and reliable

4. Secure

• API key authentication
• HTTPS encryption
• Device can't be accessed directly
• Only responds to authenticated requests

Comparison with Other Solutions

Real-World Example

Scenario: Search Your Mac from Your Phone

1. You're at a coffee shop (on your phone)
2. Your Mac is at home (connected to internet)
3. You want to find a file on your Mac

What Happens:

1. You open Sulala.ai dashboard on phone
2. You type "project proposal" and click search
3. Cloud creates pending search query
4. Your Mac (running device agent) polls for searches
5. Mac finds the file locally
6. Mac sends results to cloud
7. You see results on your phone

No IP addresses, no firewall config, no VPN needed!

Security Considerations

1. API Key Security

• Stored securely on device
• Never exposed in logs
• Can be regenerated if compromised

2. HTTPS Only

• All communication encrypted
• No plaintext data

3. Device Isolation

• Each device has unique API key
• Devices can't access each other
• User can only access their own devices

4. Search Scope Control

• Device can limit searchable folders
• User can configure permissions
• Sensitive folders excluded by default

Future Enhancements

WebSockets (Future)

For real-time communication, we can add WebSockets:

Device Agent
   ↓ WebSocket connection
Cloud Server
   ↓ Push search requests instantly
Device Agent
   ↓ Execute and respond

But polling works great for now and is simpler!

Summary

✅ No IP addresses needed - Device connects to cloud domain
✅ Works from anywhere - Outbound connections only
✅ No firewall config - No inbound ports needed
✅ Secure - API keys + HTTPS
✅ Simple - Polling pattern is reliable
✅ Scalable - Works with many devices

This is exactly how services like Dropbox, Google Drive, and remote desktop tools work!