Tonne of debugging - getting ready for the production builds
This commit is contained in:
181
mkdocs/docs/v2/backend/services/index.md
Normal file
181
mkdocs/docs/v2/backend/services/index.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Backend Services
|
||||
|
||||
Shared services provide cross-cutting functionality across the Changemaker Lite platform. These services handle external integrations, background processing, and common operations.
|
||||
|
||||
## Service Architecture
|
||||
|
||||
Services are singleton instances that provide:
|
||||
|
||||
- External API integrations (email, geocoding, newsletters)
|
||||
- Background job processing (email queues, geocoding queues)
|
||||
- Caching and data management
|
||||
- Infrastructure operations (Docker, tunneling)
|
||||
|
||||
## Core Services
|
||||
|
||||
### Email Services
|
||||
|
||||
**Email Service** (`email.service.ts`)
|
||||
|
||||
- Nodemailer SMTP wrapper
|
||||
- Template processing with variable substitution
|
||||
- Test mode support (MailHog integration)
|
||||
- HTML email generation
|
||||
- Attachment handling
|
||||
|
||||
**Email Queue Service** (`email-queue.service.ts`)
|
||||
|
||||
- BullMQ queue management
|
||||
- Worker process for async email sending
|
||||
- Job retry logic with exponential backoff
|
||||
- Queue monitoring and statistics
|
||||
- Batch email processing
|
||||
|
||||
### Geocoding Services
|
||||
|
||||
**Geocoding Service** (`geocoding.service.ts`)
|
||||
|
||||
- Multi-provider geocoding (6 providers)
|
||||
- Nominatim (OpenStreetMap)
|
||||
- ArcGIS
|
||||
- Photon
|
||||
- Mapbox
|
||||
- Google Geocoding API
|
||||
- Pelias
|
||||
- Provider fallback chain
|
||||
- Rate limiting per provider
|
||||
- Result caching
|
||||
- Batch geocoding support
|
||||
|
||||
**Geocode Queue Service** (`geocode-queue.service.ts`)
|
||||
|
||||
- BullMQ queue for async geocoding
|
||||
- Worker process with provider rotation
|
||||
- Progress tracking
|
||||
- Error handling and retry logic
|
||||
- Batch processing optimization
|
||||
|
||||
### Integration Services
|
||||
|
||||
**Listmonk Client** (`listmonk.client.ts`)
|
||||
|
||||
- Typed HTTP client for Listmonk REST API
|
||||
- Basic auth integration
|
||||
- List management operations
|
||||
- Subscriber CRUD
|
||||
- Campaign operations
|
||||
|
||||
**Listmonk Sync Service** (`listmonk-sync.service.ts`)
|
||||
|
||||
- Opt-in sync (controlled by `LISTMONK_SYNC_ENABLED`)
|
||||
- Participant → subscriber sync
|
||||
- Location → list management
|
||||
- User role → list assignment
|
||||
- Automated sync on campaign actions
|
||||
|
||||
**Pangolin Client** (`pangolin.client.ts`)
|
||||
|
||||
- Typed HTTP client for Pangolin Integration API
|
||||
- API key authentication
|
||||
- Tunnel management
|
||||
- Site configuration
|
||||
- Resource operations
|
||||
|
||||
### Infrastructure Services
|
||||
|
||||
**Docker Service** (`docker.service.ts`)
|
||||
|
||||
- Container lifecycle management
|
||||
- Health check monitoring
|
||||
- Service status queries
|
||||
- Container operations (start, stop, restart)
|
||||
- Resource monitoring
|
||||
|
||||
## Service List
|
||||
|
||||
| Service | Purpose | Dependencies |
|
||||
|---------|---------|--------------|
|
||||
| Email Service | SMTP email delivery | Nodemailer |
|
||||
| Email Queue | Async email processing | BullMQ, Redis |
|
||||
| Geocoding | Address → coordinates | Multiple providers |
|
||||
| Geocode Queue | Async geocoding | BullMQ, Redis |
|
||||
| Listmonk Client | Newsletter API | Native fetch |
|
||||
| Listmonk Sync | Automated list sync | Listmonk Client |
|
||||
| Pangolin Client | Tunnel API | Native fetch |
|
||||
| Docker Service | Container ops | Docker API |
|
||||
|
||||
## Configuration
|
||||
|
||||
Services are configured via environment variables in `api/src/config/env.ts`:
|
||||
|
||||
```typescript
|
||||
// Email
|
||||
EMAIL_TEST_MODE=true // Use MailHog instead of SMTP
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_PORT=587
|
||||
|
||||
// Geocoding
|
||||
MAPBOX_ACCESS_TOKEN=pk_...
|
||||
GOOGLE_GEOCODE_API_KEY=...
|
||||
|
||||
// Listmonk
|
||||
LISTMONK_SYNC_ENABLED=true
|
||||
LISTMONK_API_URL=http://listmonk:9000
|
||||
LISTMONK_API_USER=api_user
|
||||
LISTMONK_API_TOKEN=secret
|
||||
|
||||
// Pangolin
|
||||
PANGOLIN_API_URL=https://api.bnkserve.org/v1
|
||||
PANGOLIN_API_KEY=...
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Email Service
|
||||
|
||||
```typescript
|
||||
import { emailService } from '../services/email.service';
|
||||
|
||||
await emailService.sendEmail({
|
||||
to: 'user@example.com',
|
||||
subject: 'Welcome',
|
||||
html: '<p>Welcome to our platform</p>',
|
||||
});
|
||||
```
|
||||
|
||||
### Email Queue
|
||||
|
||||
```typescript
|
||||
import { emailQueueService } from '../services/email-queue.service';
|
||||
|
||||
await emailQueueService.addEmailJob({
|
||||
to: 'user@example.com',
|
||||
subject: 'Campaign Update',
|
||||
template: 'campaign-email',
|
||||
variables: { campaignName: 'Save the Parks' },
|
||||
});
|
||||
```
|
||||
|
||||
### Geocoding Service
|
||||
|
||||
```typescript
|
||||
import { geocodingService } from '../services/geocoding.service';
|
||||
|
||||
const result = await geocodingService.geocode({
|
||||
address: '123 Main St, Toronto, ON',
|
||||
provider: 'nominatim',
|
||||
});
|
||||
|
||||
if (result.success) {
|
||||
console.log(result.coordinates); // { lat: 43.65, lng: -79.38 }
|
||||
}
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Backend Overview](../index.md)
|
||||
- [Modules](../modules/index.md)
|
||||
- [Environment Variables](../../deployment/environment-variables.md)
|
||||
- [Email Queue Feature](../../features/influence/email-queue.md)
|
||||
- [Geocoding Feature](../../features/map/geocoding.md)
|
||||
- [Newsletter Integration](../../features/newsletter/index.md)
|
||||
Reference in New Issue
Block a user