How rapidpro/mailroom works
Main Components
a. Core Services:
• Web Server (HTTP API Layer)
• Message Processing Engine (Mailroom Core)
• Flow Engine (GoFlow)
• Task Workers/Handlers
• Queue Management System
b. External Dependencies:
• PostgreSQL Database (Primary + Read-only replica)
• Redis
• ElasticSearch
• AWS S3
• SMTP Server
• Firebase Cloud Messaging
• External Services (Courier, RapidPro)
Component Relationships
[External Clients] → [Web Server Layer (/:8090)]
• ↓
[RapidPro Platform] ← [Core Services]
• ↓
[Message Engine] ← → [Flow Engine (GoFlow)]
• ↓
[Task Workers] → [Queue Management]
• ↓
[Service Handlers]
• ↓
[External Services Layer]
Key Architectural Elements
a. Data Flow Paths:
• Task distribution through the queue system
• Data persistence flows to databases
• Webhook and external service interactions
• Core Services (Rectangle): Web, Engine, Workers
• External Services (Cloud): Courier, FCM, SMTP
• Queue System (Queue symbol): Redis-based queuing
• Processing Units (Hexagon): Task handlers, Flow engine
Specific Implementation Details
a. Core Modules (group together):
• Models (/core/models)
• Handlers (/core/handlers)
• Tasks (/core/tasks)
• Queue Management (/core/queue)
• Runner (/core/runner)
b. Service Integration Points:
• IVR Services (Twiml, Vonage)
• Ticket Services (Zendesk, RocketChat, Mailgun)
• Message Services (Courier integration)
Important Architectural Patterns
• Worker Pool Pattern: Show task distribution system
• Queue-based Architecture: Highlight message processing flow
• Service Layer Pattern: External service integration
• Repository Pattern: Data access layer
Top Level:
[Client Layer] → [API Gateway]
• ↓
[Processing Layer]
• ↓
[Storage Layer]
Middle Layer (Processing):
[Task Handlers] ← → [Queue Manager]
• ↓
[Flow Engine] ← → [Message Processor]
Bottom Layer (Storage/External):
[PostgreSQL] [Redis] [ElasticSearch] [S3]
[External Services: Courier, FCM, SMTP]