Skip to content

Discovery & Routing Service (discovery-service)

The discovery-service runs a Netflix Eureka service registry for the SMS Gateway cluster.

  • Dynamic Registration: Every microservice (client-service, sms-router-service, etc.) registers its IP address and port with Eureka upon startup.
  • Client-Side Load Balancing: Services use Spring Cloud LoadBalancer to look up target service locations dynamically.
  • Internal Routing: For example, when the gateway forwards requests downstream, it targets lb://client-service or lb://sms-router-service, letting Eureka resolve the physical host.

Discovery & Routing Flow

flowchart LR
    Client[External Client] -->|HTTP request| Gateway[gateway-service]

    Discovery[(discovery-service<br/>Eureka Registry)]

    Gateway -->|Register instance<br/>name, host, port| Discovery
    ClientSvc[client-service] -->|Register instance<br/>name, host, port| Discovery
    Router[sms-router-service] -->|Register instance<br/>name, host, port| Discovery
    Aggregator[aggregator-integration-service] -->|Register instance<br/>name, host, port| Discovery

    Gateway -->|Fetch registry| Discovery
    Gateway -->|lb://client-service| ClientSvc
    Gateway -->|lb://sms-router-service| Router

    Router -.->|Can discover internal services| Discovery
    Aggregator -.->|Can discover internal services| Discovery
Hold "Ctrl" to enable pan & zoom

The service discovery and dynamic routing process operates through the following lifecycle:

  1. Service Registration: Upon startup, each microservice instance registers its metadata (application name, IP address, port, and health check URLs) with the Eureka server (discovery-service).
  2. Heartbeats & Lease Renewal: Instances send periodic heartbeats (configured to every 10 seconds in dev/prod) to renew their lease. This signals to Eureka that the instance is active.
  3. Lease Expiration & Eviction: If Eureka does not receive a heartbeat within the lease expiration time (configured to 30 seconds), the instance is considered unhealthy and is evicted from the registry.
  4. Registry Fetching: Downstream clients, such as the gateway-service, periodically fetch and cache the active registry database (configured to every 2 seconds).
  5. Logical Name Resolution & Load Balancing: The gateway does not need fixed backend hostnames. When routing incoming requests, it resolves logical service names against its local registry cache:
Gateway Route Target Resolved By Typical Path Predicates
lb://client-service Eureka registry lookup /auth/**, /api/**, /admin/clients/**, /admin/reports/**, /internal/clients/**
lb://sms-router-service Eureka registry lookup /api/sms/**, /api/campaigns/**, /admin/sms-config/**

When a backend instance restarts or scales horizontally, it refreshes its registration in Eureka, and the gateway dynamically updates its load-balanced routing targets.