How faijanbaig/pearl works
Project type and purpose
• This is a backend microservice built with Node.js and Express that exposes a REST API for sending emails.
• Key features: retry logic with exponential backoff, provider fallback, idempotency, rate limiting, queueing, and logging.
File structure
• index.js: server bootstrap (listens on PORT).
• app.js: configures Express app (middleware, routes, error handling).
• src/routes/emailSender.route.js: defines the POST /api/v0/send-email endpoint.
• src/controllers/emailSender.controller.js: handler that delegates to the service layer.
• src/middlewares/emailValidation.util.js: validates incoming payloads.
• src/services/emailService.service.js: core business logic (queueing, retry, fallback, idempotency, rate limiting).
• src/utils:
• ApiError.util.js & ApiResponse.util.js for uniform error/response formatting.
• asyncHandler.util.js wraps async controllers.
• emailProvider.util.js encapsulates interactions with external email providers.
• tests/: Jest tests for providers and service logic.
Main components
a. External Client (e.g. UI or another service)
b. API Gateway / Express Server (index.js & app.js)
c. Routing Layer (emailSender.route)
d. Middleware Layer
– Validation Middleware
– Rate Limiting Middleware (if implemented here or in the service)
– Idempotency Check (could be middleware or part of the service)
e. Controller Layer (emailSender.controller)
f. Service Layer (emailService.service)
– Queue Manager
– Retry & Exponential Backoff Logic
– Fallback Orchestrator
– Idempotency Store (in-memory or persistent store)
g. External Email Providers (Primary and Secondary)
h. Logging & Monitoring Module (could be part of utils or external)
i. (Optional) Persistence Layer for tracking status & idempotency keys
Relationships and interactions
1. Client sends HTTP POST to /api/v0/send-email
2. Express routes request to validation middleware → rate‐limiter/idempotency
3. Controller receives validated payload and invokes Service Layer
4. Service enqueues the job, then:
• Attempts send via Primary Provider
• On failure, applies retry logic (exponential backoff)
• If all retries fail, switches to Secondary Provider (fallback)
• Records idempotency key and final status in store
5. Service returns success or error response via Controller → Express → Client
6. All steps log events/errors for debugging and monitoring
Architectural patterns & design principles
• Layered (MVC-like) separation: Routes → Controllers → Services → Utils
• Single Responsibility: validation, error handling, response formatting extracted into utils/middleware
• Resilience Patterns: retry with backoff, circuit-breaker-like fallback, idempotency checks
• Asynchronous job processing (queue) to decouple request-response from external calls
• External clouds: Primary Email Provider, Secondary Email Provider