atlas/docs/INTEGRATION_DESIGN.md

Integration Design Documents

Design documents for optional integrations (email, calendar, smart home).

Overview

These integrations are marked as "optional" and can be implemented after MVP. They require:

• External API access (with privacy considerations)
• Confirmation flows (high-risk actions)
• Boundary enforcement (work vs family separation)

Email Integration (TICKET-036)

Design Considerations

Privacy:

• Email access requires explicit user consent
• Consider local email server (IMAP/SMTP) vs cloud APIs
• Family agent should NOT access work email

Confirmation Required:

• Sending emails is CRITICAL risk
• Always require explicit confirmation
• Show email preview before sending

Tools:

• list_recent_emails - List recent emails (read-only)
• read_email - Read specific email
• draft_email - Create draft (no send)
• send_email - Send email (requires confirmation token)

Implementation:

• Use IMAP for reading (local email server)
• Use SMTP for sending (with authentication)
• Or use email API (Gmail, Outlook) with OAuth

Calendar Integration (TICKET-037)

Design Considerations

Privacy:

• Calendar access requires explicit user consent
• Separate calendars for work vs family
• Family agent should NOT access work calendar

Confirmation Required:

• Creating/modifying/deleting events is HIGH risk
• Always require explicit confirmation
• Show event details before confirming

Tools:

• list_events - List upcoming events
• get_event - Get event details
• create_event - Create event (requires confirmation)
• update_event - Update event (requires confirmation)
• delete_event - Delete event (requires confirmation)

Implementation:

• Use CalDAV for local calendar server
• Or use calendar API (Google Calendar, Outlook) with OAuth
• Support iCal format

Smart Home Integration (TICKET-038)

Design Considerations

Privacy:

• Smart home control is HIGH risk
• Require explicit confirmation for all actions
• Log all smart home actions

Confirmation Required:

• All smart home actions are CRITICAL risk
• Always require explicit confirmation
• Show action details before confirming

Tools:

• list_devices - List available devices
• get_device_status - Get device status
• toggle_device - Toggle device on/off (requires confirmation)
• set_scene - Set smart home scene (requires confirmation)
• adjust_thermostat - Adjust temperature (requires confirmation)

Implementation:

• Use Home Assistant API (if available)
• Or use device-specific APIs (Philips Hue, etc.)
• Abstract interface for multiple platforms

Common Patterns

Confirmation Flow

All high-risk integrations follow this pattern:

1. Agent proposes action: "I'll send an email to..."
2. User confirms: "Yes" or "No"
3. Confirmation token generated: Signed token with action details
4. Tool validates token: Before executing
5. Action logged: All actions logged for audit

Boundary Enforcement

• Family Agent: Can only access family email/calendar
• Work Agent: Can access work email/calendar
• Smart Home: Both can access, but with confirmation

Error Handling

• Network errors: Retry with backoff
• Authentication errors: Re-authenticate
• Permission errors: Log and notify user

Implementation Priority

1. Smart Home (if Home Assistant available) - Most useful
2. Calendar - Useful for reminders and scheduling
3. Email - Less critical, can use web interface

Security Considerations

• OAuth Tokens: Store securely, never in code
• API Keys: Use environment variables
• Rate Limiting: Respect API rate limits
• Audit Logging: Log all actions
• Token Expiration: Handle expired tokens gracefully

Future Enhancements

• Voice confirmation ("Yes, send it")
• Batch operations
• Templates for common actions
• Integration with memory system (remember preferences)