Skip to Content
OverviewIntegrations

Integrations

Overview of existing and planned external integrations including push notifications, WebSocket, and third-party services.

This document describes existing and planned integrations in Oter.

Current Integrations

Transaction Import

Purpose: Import transactions from bank statements or CSV files

Implementation:

  • Location: server/src/main/kotlin/com/esteban/ruano/utils/TransactionParser.kt
  • API Endpoint: POST /finance/transactions/import-preview
  • Format Support:
    • Plain text (description, date, amount per line)
    • CSV files
    • Bank statement formats

How It Works:

  1. User uploads file or pastes text
  2. TransactionParser parses the text
  3. System extracts transaction details (description, date, amount)
  4. Category keywords are matched to suggest categories
  5. Preview shown to user for confirmation
  6. User confirms and transactions are imported

Authentication: Requires valid JWT token

Security Considerations:

  • File size limits to prevent DoS
  • Content validation to prevent injection attacks
  • User-specific imports (transactions associated with authenticated user)

AWS S3 Integration

Purpose: Store user-uploaded files (icons, images, documents)

Implementation:

  • Location: server/src/main/kotlin/com/esteban/ruano/service/StudyImageService.kt
  • AWS SDK: AWS S3 client for file uploads
  • Bucket Configuration: Environment-based bucket names

How It Works:

  1. User uploads file through UI
  2. Server receives file
  3. File validated (type, size)
  4. Unique filename generated
  5. File uploaded to S3
  6. Public URL returned to client

Security Considerations:

  • Pre-signed URLs for secure access
  • File type validation
  • Size limits
  • User-specific paths to prevent unauthorized access

AWS SES (Simple Email Service)

Purpose: Send transactional emails (password reset, notifications)

Implementation:

  • Location: server/src/main/kotlin/com/esteban/ruano/utils/SesEmailSender.kt
  • AWS SDK: AWS SES client

Use Cases:

  • Password reset emails
  • Account verification
  • Notification emails (future)

Security Considerations:

  • Email templates to prevent injection
  • Rate limiting to prevent abuse
  • SPF/DKIM configuration for deliverability

Firebase Cloud Messaging (FCM)

Purpose: Push notifications to mobile devices

Implementation:

  • Location: server/src/main/kotlin/com/esteban/ruano/service/NotificationService.kt
  • Firebase Admin SDK: Server-side FCM integration

Use Cases:

  • Timer completion notifications
  • Habit reminders
  • Task due date reminders
  • Financial alerts (future)

Security Considerations:

  • Device token validation
  • User-specific notifications only
  • Notification content sanitization

PostgreSQL Database

Purpose: Primary data storage

Implementation:

  • ORM: Exposed framework
  • Connection Pooling: HikariCP
  • Migrations: Flyway

Features:

  • User data isolation
  • Transaction support
  • Indexed queries for performance
  • Backup and recovery

WebSocket Integration

Purpose: Real-time updates for timers and notifications

Implementation:

  • Location: server/src/main/kotlin/com/esteban/ruano/service/TimerNotifier.kt
  • Protocol: WebSocket over HTTP
  • Client: shared/src/commonMain/kotlin/com/esteban/ruano/oter/websocket/TimerWebSocketClient.kt

Use Cases:

  • Real-time timer updates
  • Timer state synchronization
  • Multi-device timer sync

Security Considerations:

  • JWT authentication on connection
  • User-specific channels
  • Heartbeat to detect disconnections

Planned Integrations

Bank API Integration

Status: Planned

Purpose: Automatically import transactions from bank accounts

Requirements:

  • Open Banking API support (Plaid, Yodlee, etc.)
  • OAuth flow for bank authentication
  • Secure credential storage
  • Transaction categorization

Security Considerations:

  • Encrypted credential storage
  • Read-only access (no write permissions)
  • Token refresh handling
  • Compliance with financial regulations

CSV Export

Status: Planned

Purpose: Export transactions and predictions to CSV

Implementation:

  • Generate CSV from transaction data
  • Include all relevant fields
  • Support for Excel compatibility

Calendar Integration

Status: Planned

Purpose: Sync scheduled transactions and tasks with calendar apps

APIs:

  • Google Calendar API
  • Apple Calendar (CalDAV)
  • Outlook Calendar API

Features:

  • Two-way sync
  • Event creation from scheduled transactions
  • Reminder integration

Budget Tracking Apps

Status: Planned

Purpose: Export data to popular budgeting apps

Formats:

  • OFX (Open Financial Exchange)
  • QIF (Quicken Interchange Format)
  • CSV for generic import

Analytics Integration

Status: Future

Purpose: User behavior analytics (privacy-respecting)

Options:

  • Self-hosted analytics
  • Privacy-focused third-party services
  • Optional opt-in only

Integration Architecture

Current integrations (solid lines) and planned integrations (dashed) for the Oter server.

Authentication Pattern

Most integrations follow this pattern:

  1. User initiates: User clicks “Connect” or similar
  2. OAuth flow: Redirect to third-party service
  3. Authorization: User grants permissions
  4. Token storage: Encrypted storage of access tokens
  5. Token refresh: Automatic token refresh when expired
  6. Data sync: Periodic or on-demand data synchronization

Error Handling

Integrations include robust error handling:

  • Network errors: Retry with exponential backoff
  • Authentication errors: Re-authenticate flow
  • Rate limiting: Respect API rate limits
  • Data validation: Validate imported data before storage

Data Synchronization

Synchronization strategies:

  • Pull: Periodic fetching from external source
  • Push: Sending data to external service
  • Real-time: WebSocket or webhook-based updates
  • On-demand: User-triggered sync

Security Best Practices

Credential Storage

  • Encryption: All credentials encrypted at rest
  • Key management: AWS Secrets Manager or similar
  • Access control: Least privilege principle
  • Rotation: Regular credential rotation

API Security

  • Rate limiting: Prevent abuse
  • Input validation: Sanitize all inputs
  • Output encoding: Prevent injection attacks
  • HTTPS only: All external communication encrypted

Data Privacy

  • User consent: Explicit consent for data sharing
  • Data minimization: Only necessary data shared
  • Retention policies: Automatic data deletion
  • GDPR compliance: Right to deletion, data portability

Monitoring and Logging

Integration Health

  • Health checks: Periodic checks of integration status
  • Error tracking: Sentry integration for error monitoring
  • Metrics: Success/failure rates, latency
  • Alerts: Notifications for integration failures

Logging

  • Structured logging: JSON format for parsing
  • Sensitive data: Never log credentials or PII
  • Log levels: Appropriate levels for different events
  • Retention: Configurable log retention periods
UI & UXTesting & QA