Overview

HopeConnect integrates with several third-party services to enhance functionality. This document details each integration's purpose, implementation, and configuration.

1. OpenCage Geocoding API

Purpose

• Convert physical addresses to geographic coordinates (latitude/longitude)
• Calculate distances between volunteer locations and service requests

Implementation

@Service
public class GeocodingService {
    private final String apiKey = "e958df22a8a74bf08e6165a4b13db0d5";

    public Map<String, Float> getGeocodingData(String address) throws IOException {
        // Implementation details...
    }
}

Configuration

Parameter	Value
API Endpoint	https://api.openagedata.com/geocode/v1/json
Rate Limit	2,500 requests/day (free tier)
Response Format	JSON

Usage

// Example usage  
Map<String, Float> coords = geocodingService.getGeocodingData("123 Main St");  
float lat = coords.get("lat");  
float lng = coords.get("lng");  

2. Stripe Payment API

Purpose

• Process donations and payments
• Handle emergency campaign funding
• Manage sponsorship transactions

Implementation

@Service  
public class EmergencyStripeService {  
    @Value("${stripe.secretKey}")  
    private String secretKey;  

    public StripeResponse createDonationSession(EmergencyDonationRequest request) {  
        // Implementation details...  
    }  
} 

Configuration

Parameter	Value
API Version	2022-11-15
Payment Types	Credit/Debit Cards
Currency	Configurable (default: USD)
Webhook URLs	Success/Cancel callbacks

Flow

1. Create checkout session
2. Redirect user to Stripe
3. Handle success/cancel callbacks
4. Verify payment via webhook

3. ChatGPT API

Purpose

• Generate compassionate orphan reports
• Automate content creation
• Provide intelligent summaries

Implementation

@Service  
public class ChatbotService {  
    @Value("${chatbot.api.url}")  
    private String apiUrl;  

    @Value("${chatbot.api.key}")  
    private String apiKey;  

    public String generateOrphanReport(Orphan orphan) {  
        // Implementation details...  
    }  
}

Configuration

Parameter	Value
Model	gpt-3.5-turbo
Max Tokens	300
Temperature	Default (0.7)
API Endpoint	Configurable via properties

Example Prompt

Generate a compassionate report for:  
Name: [Name]  
Gender: [Gender]  
DoB: [Date]  
Education: [Status]  
Health: [Condition]  

4. Email Service (SMTP)

Purpose

• Send verification emails
• Notify donors/orphans
• Confirm partnerships
• Transaction receipts

Implementation

@Service("emailSenderService")  
public class EmailSenderService {  
    private final JavaMailSender javaMailSender;  

    @Async  
    public void sendEmail(String toEmail, String subject, String body) {  
        // Implementation details...  
    }  
} 

Configuration

Parameter	Value
Protocol	SMTP
Authentication	Spring Mail configured
Async	Enabled
TLS	Enabled by default

Email Types

1. Verification Emails
   • New partnerships
   • Account confirmations
2. Notification Emails
   • Donation receipts
   • Application updates
3. Alert Emails
   • Emergency campaigns
   • Urgent requests

Error Handling

Service	Strategy
Geocoding	Retry logic + fallback cache
Stripe	Webhook verification + logging
ChatGPT	Error message fallback
Email	Async retry queue

Rate Limits

Rate Limits

API	Limit	Additional Notes
OpenCage	2,500 requests/day	Free tier limit
Stripe	100 requests/second	Across all endpoints
ChatGPT	3,500 requests/minute	GPT-3.5-turbo model
Email (Gmail)	500 emails/day	For free Gmail accounts
	2,000 emails/day	For Google Workspace accounts
	100 recipients/email	Total per message
	1.5MB message size	Including attachments

Important Gmail-Specific Limits:

1. Daily Sending Limits:

   • Regular Gmail: 500 emails/day
   • Google Workspace: 2,000 emails/day (can be increased with paid plans)

2. Per Email Limits:

   • Max 100 recipients per message (To/Cc/Bcc combined)
   • 24-hour rolling window for limits

3. Other Restrictions:

   • Auto-batching recommended for bulk sends
   • Sudden spikes may trigger temporary blocks
   • Strict anti-spam policies apply

Recommendations:

1. For production systems, consider:

   • SMTP Relay Service (3,000 emails/day)
   • Google Workspace with higher limits
   • Dedicated Email APIs (SendGrid, Mailgun, etc.)

2. Implementation Tips:

// Recommended email sending pattern with Gmail
@Async
@Scheduled(fixedDelay = 60000) // Throttle to 1 email/sec
public void sendWithRateLimit(EmailMessage message) {
    if (dailyCount < 500) { // Gmail free tier limit
        javaMailSender.send(message);
        dailyCount++;
    }
}

Security

1. All APIs

• Secrets stored in environment variables
• Encrypted in transit (HTTPS)
• Rate limiting

2. Stripe Specific

• PCI DSS compliant
• Webhook signature verification

3. Email Specific

• SPF/DKIM configured
• No sensitive data in body