Overview
The Usheru Geo API provides geographic information based on an IP address.
It is designed to be consumed from both embedded widgets on websites and server-side rendered (SSR) applications, delivering accurate user location data without relying on third-party services.
The service offers:
IP-to-Location resolution: returning city, latitude, and longitude from an IP.
Scalability and resilience thanks to a cloud-native architecture.
Architecture Overview
The deployment of the Geo API is fully cloud-based:
CloudFront: entry point that manages CORS policies and distributes traffic globally.
ECS Fargate: the service runs on two container instances for high availability and load balancing. Each container hosts the Node.js application built with Yarn, Vite, Express, and TypeScript.
GeoLite2-City database: MaxMind .mmdb file stored in an S3 bucket, accessed at runtime by the service.
CodePipeline: continuous integration pipeline that builds and deploys the service on every commit to the main branch, ensuring zero-downtime updates.
Request Flow
A client (widget or SSR application) sends an HTTP request to the public API domain.
CloudFront receives the request, applies CORS rules, and forwards it to ECS.
One of the ECS Fargate tasks processes the request:
If the request targets /api/ip, the provided IP is validated and resolved using the GeoLite2-City database.
If the request targets /api/ip-address, the client’s public IP is returned.
The service responds in JSON format with the relevant information.
Usheru-geo Service
The application follows a layered Express architecture for maintainability and scalability.
1. Service Layer
Responsible for accessing the GeoLite2-City database.
Implements the business logic, such as:
Validating and parsing the IP.
Querying the .mmdb file.
Transforming raw results into normalized JSON responses (ip, city, latitude, longitude).
2. Middleware Layer
Processes requests before they reach the controller.
Common responsibilities:
Centralized error handling.
Logging of requests and responses.
Header configuration (when required).
3. Routes Layer
Defines the available endpoints and maps them to controllers.
Example mappings:
/api/ip → GeoController.getByIp
/api/ip-address → GeoController.getClientIp (Will be deprecated)
4. Controller Layer
Main entry point for each request.
Retrieves query parameters, delegates logic to the Service Layer, and builds the JSON response.
Ensures proper HTTP status codes:
200 for successful requests.
400 for invalid IP addresses.
500 for internal server errors.
4.1 Automatic IP detection
If no IP is explicitly provided in the query, the controller attempts to detect the client IP automatically, using common headers and socket information in order of priority:
Query parameter ?ip= → used when the caller explicitly provides the IP.
Header x-client-ip → typically added by SSR applications when the server forwards the client’s IP along with the request.
Header x-forwarded-for → common in proxy/load balancer setups (CloudFront or other CDNs). If multiple IPs are present, the first one is selected.
Socket remoteAddress → fallback to the direct TCP connection address (may expose internal load balancer IPs if not behind proxies).
Benefits of this layered design:
Clear separation of concerns.
High testability (each layer can be unit-tested).
Easy extensibility for new routes or features.
Reusability of service logic across multiple endpoints.
API Specification
The API exposes two main routes:
/api/ip
Purpose: Returns geographic information for a given IP.
Parameters:
ip (required) → IP address to resolve.
Responses:
200 OK: JSON with IP, city, latitude, longitude.
400 Bad Request: Invalid IP address.
500 Internal Server Error: Unexpected failure.
/api/ip-address (Will be deprecated)
Purpose: Returns the client’s public IP as detected by the API.
Responses:
200 OK: JSON with the client IP.
500 Internal Server Error: Unexpected failure.
Security and Compliance
The service does not persist IP addresses; they are only processed in memory.
The GeoLite2-City database is licensed by MaxMind and must be updated regularly to maintain accuracy.
Development & Build
Build, test, and deployment processes are defined in the repository.
👉 For local setup, testing, and environment configuration, refer to the project’s README.
Deployment and Operations
CI/CD: Every commit to main triggers CodePipeline, which builds the application (Yarn + Vite), creates a new Docker image, and updates ECS tasks automatically.
Scalability: ECS with Fargate supports elastic scaling; more tasks can be added without changing the architecture.
Global performance: CloudFront ensures low latency worldwide and enforces CORS for external widget consumption.