Summary
Integrate ipapi.co (or ipapi.is) to resolve the requester's IP address to geographic metadata — country, region, city, timezone, and currency. Used for locale-aware UX, fraud signals, and rate-limiting by region.
Scope
Backend (Go)
- Add a
Geolocator interface in usecase/ with a Lookup(ip string) (*domain.GeoLocation, error) method
- Add
domain/geolocation.go with a GeoLocation entity (country code, country name, region, city, timezone, currency, is_eu)
- Implement in
internal/infrastructure/geo/ipapi/ using the ipapi HTTP API
- Cache results in Redis (TTL ~24h) by IP to avoid hammering the API rate limit — reuses the existing Redis client
- Expose a middleware helper
GeoFromRequest() that extracts the real IP (respecting X-Forwarded-For from Railway's proxy) and attaches a *domain.GeoLocation to the Gin context
- Wire the client in
server.go using IPAPI_KEY env var (optional — ipapi has a free tier without a key)
- Add
IPAPI_KEY to backend/.env.example
Usage points
Acceptance criteria
Dependencies
- Existing Redis infrastructure — caching layer
Summary
Integrate ipapi.co (or
ipapi.is) to resolve the requester's IP address to geographic metadata — country, region, city, timezone, and currency. Used for locale-aware UX, fraud signals, and rate-limiting by region.Scope
Backend (Go)
Geolocatorinterface inusecase/with aLookup(ip string) (*domain.GeoLocation, error)methoddomain/geolocation.gowith aGeoLocationentity (country code, country name, region, city, timezone, currency, is_eu)internal/infrastructure/geo/ipapi/using the ipapi HTTP APIGeoFromRequest()that extracts the real IP (respectingX-Forwarded-Forfrom Railway's proxy) and attaches a*domain.GeoLocationto the Gin contextserver.gousingIPAPI_KEYenv var (optional — ipapi has a free tier without a key)IPAPI_KEYtobackend/.env.exampleUsage points
Acceptance criteria
GeoLocatorinterface andGeoLocationdomain entity existGeoFromRequest()middleware correctly extracts IP behind Railway's proxyIPAPI_KEYinbackend/.env.example(marked optional with comment)backend/docs/geolocation.mdDependencies