# faijanbaig/pearl architecture

> Architecture diagram of the GitHub repository faijanbaig/pearl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faijanbaig/pearl
- Repository: https://github.com/faijanbaig/pearl

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["External Client"]:::external

    %% API Gateway
    subgraph "API Gateway / Express Server"
        direction TB
        ExpressIndex["index.js"]:::apiGateway
        ExpressApp["app.js"]:::apiGateway
    end

    %% Routing Layer
    subgraph "Routing Layer"
        direction TB
        Router["emailSender.route.js"]:::middleware
    end

    %% Middleware & Controller
    subgraph "Middleware & Controller"
        direction TB
        Validation["emailValidation.util.js"]:::middleware
        RateLimiter["Rate Limiting / Idempotency"]:::middleware
        Controller["emailSender.controller.js"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        Service["emailService.service.js"]:::service
        subgraph "Core Business Logic"
            direction TB
            Queue["Queue Manager"]:::service
            Retry["Retry & Exponential Backoff"]:::service
            Fallback["Fallback Orchestrator"]:::service
            IdempotencyStore["Idempotency Store"]:::datastore
        end
    end

    %% Utils
    subgraph "Utilities"
        direction TB
        EmailProvider["emailProvider.util.js"]:::utils
        ApiError["ApiError.util.js"]:::utils
        ApiResponse["ApiResponse.util.js"]:::utils
        AsyncHandler["asyncHandler.util.js"]:::utils
    end

    %% External Providers
    subgraph "External Email Providers"
        direction TB
        Primary["Primary Email Provider"]:::external
        Secondary["Secondary Email Provider"]:::external
    end

    %% Data Flow
    Client -->|"POST /api/v0/send-email"| ExpressIndex
    ExpressIndex --> ExpressApp
    ExpressApp -->|routes to| Router
    Router -->|validates| Validation
    Validation -->|checks rate/idempotency| RateLimiter
    RateLimiter --> Controller
    Controller -->|calls| Service
    Service --> Queue
    Queue --> Retry
    Retry --> Primary
    Retry -->|on failure| Fallback
    Fallback --> Secondary
    Service --> IdempotencyStore
    Service --> Controller
    Controller --> ExpressApp
    ExpressApp --> Client

    %% Utils interactions
    Controller --> AsyncHandler
    Service --> EmailProvider
    Any--> ApiError
    Any--> ApiResponse

    %% Click Events
    click ExpressIndex "https://github.com/faijanbaig/pearl/blob/master/index.js"
    click ExpressApp "https://github.com/faijanbaig/pearl/blob/master/app.js"
    click Router "https://github.com/faijanbaig/pearl/blob/master/src/routes/emailSender.route.js"
    click Validation "https://github.com/faijanbaig/pearl/blob/master/src/middlewares/emailValidation.util.js"
    click Controller "https://github.com/faijanbaig/pearl/blob/master/src/controllers/emailSender.controller.js"
    click Service "https://github.com/faijanbaig/pearl/blob/master/src/services/emailService.service.js"
    click EmailProvider "https://github.com/faijanbaig/pearl/blob/master/src/utils/emailProvider.util.js"
    click ApiError "https://github.com/faijanbaig/pearl/blob/master/src/utils/ApiError.util.js"
    click ApiResponse "https://github.com/faijanbaig/pearl/blob/master/src/utils/ApiResponse.util.js"
    click AsyncHandler "https://github.com/faijanbaig/pearl/blob/master/src/utils/asyncHandler.util.js"
    click Queue "https://github.com/faijanbaig/pearl/blob/master/src/services/emailService.service.js"
    click Retry "https://github.com/faijanbaig/pearl/blob/master/src/services/emailService.service.js"
    click Fallback "https://github.com/faijanbaig/pearl/blob/master/src/services/emailService.service.js"
    click IdempotencyStore "https://github.com/faijanbaig/pearl/blob/master/src/services/emailService.service.js"

    %% Styles
    classDef apiGateway fill:#cce5ff,stroke:#004085,color:#004085;
    classDef middleware fill:#d4edda,stroke:#155724,color:#155724;
    classDef controller fill:#d4edda,stroke:#155724,color:#155724;
    classDef service fill:#fff3cd,stroke:#856404,color:#856404;
    classDef datastore fill:#e2e3e5,stroke:#383d41,color:#383d41;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
    classDef utils fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
