bitip/docs/prd-geoip-service.md

Product Requirements Document: Bitip - GeoIP Lookup Service

Introduction/Overview

Bitip is a comprehensive solution that provides IP geolocation data through a REST API and user-friendly web interface. The service solves the problem of needing quick, reliable access to geographical information about IP addresses for various use cases including application development, network monitoring, and user location detection.

The primary goal is to create a lightweight, containerized service that can serve both technical users (developers, system administrators) and end users who need to look up IP location information.

Goals

1. Provide reliable GeoIP data access - Deliver accurate geographical information for IP addresses using MaxMind databases
2. Support multiple user types - Serve internal developers, external clients, system administrators, and end users
3. Enable flexible API consumption - Support both single IP queries and batch operations
4. Offer intuitive web interface - Provide a user-friendly frontend for direct IP lookups with map visualization
5. Ensure easy deployment - Package as a single Docker container with configurable runtime options
6. Maintain performance standards - Handle concurrent requests efficiently with appropriate rate limiting

User Stories

For Internal Developers

• As an internal developer, I want to query IP geolocation data via REST API so that I can integrate location features into my applications
• As an internal developer, I want to perform batch IP lookups so that I can process multiple IPs efficiently

For External Clients

• As an external client, I want to access GeoIP data through API keys so that I can build location-aware services
• As an external client, I want clear error messages when my requests fail so that I can handle exceptions properly

For System Administrators

• As a system administrator, I want to monitor network traffic origins so that I can identify suspicious activities
• As a system administrator, I want configurable rate limiting so that I can protect the service from abuse

For End Users

• As an end user, I want to see my current IP location automatically so that I can verify my network information
• As an end user, I want to enter any IP address and see its location on a map so that I can research IP origins
• As an end user, I want to view detailed location information so that I can understand the geographical context

Functional Requirements

API Requirements

1. The system must provide a GET endpoint /api/lookup?ip={ip_address} for single IP queries
2. The system must provide a POST endpoint /api/lookup/batch accepting an array of IP addresses
3. The system must return basic location data (country, city, region, coordinates) for simple queries
4. The system must provide endpoints that return all available MaxMind database information
5. The system must validate IP addresses and return HTTP 400 for invalid inputs
6. The system must return HTTP 404 when IP addresses are not found in the database
7. The system must return HTTP 400 for private/local IP addresses (192.168.x.x, 10.x.x.x, 127.x.x.x)
8. The system must support API key authentication with configurable rate limiting
9. The system must limit batch requests to a maximum of 100 IPs (configurable via environment variable)
10. The system must implement different rate limiting for frontend vs external API consumers

Frontend Requirements

11. The system must automatically detect and display the user's current IP address on page load
12. The system must provide an editable text field for IP address input
13. The system must implement a 2000ms debounce delay (configurable) for IP input changes
14. The system must display comprehensive location data in a professional layout
15. The system must show a static map preview of the IP location
16. The system must provide a button to open an interactive map popup with zoom/pan capabilities
17. The system must use a free, open-source map provider (OpenStreetMap recommended)
18. The system must handle and display API errors gracefully to users

Infrastructure Requirements

19. The system must serve both backend API and frontend from a single port
20. The system must support configurable base path (default: "/")
21. The system must integrate with Seq logging with configurable URL and secrets
22. The system must read MaxMind databases from a configurable directory path
23. The system must be packaged as a single Docker image
24. The system must support environment variable configuration for all runtime settings

Non-Goals (Out of Scope)

• Real-time IP tracking or monitoring - This service provides lookup capabilities only, not continuous monitoring
• IP reputation or security scoring - The service focuses on geographical data, not security analysis
• Historical IP data tracking - No storage or tracking of previous lookups
• User account management - API keys are configuration-based, not user-registered
• Advanced analytics or reporting - Simple usage metrics only
• Custom map styling or branding - Standard map provider appearance
• Mobile-specific UI optimizations - Responsive design but not mobile-native features
• Integration with external notification systems - Logging to Seq only

Design Considerations

Frontend Design

• Clean, professional layout inspired by existing GeoIP services
• Responsive design that works on desktop and mobile browsers
• Intuitive user flow: IP detection → display → optional editing → results
• Clear visual hierarchy with location data prominently displayed
• Map integration with both static preview and interactive popup options

API Design

• RESTful endpoints following standard HTTP conventions
• Consistent JSON response format across all endpoints
• Clear error messaging with appropriate HTTP status codes
• Rate limiting headers to inform clients of usage limits

Technical Considerations

Dependencies

• MaxMind GeoIP2 Node.js library (@maxmind/geoip2-node) for database access
• Express.js with TypeScript for API framework
• React with Vite for frontend development
• Free map provider (OpenStreetMap via Leaflet.js recommended)

Configuration Management

• Environment variables for all runtime configuration
• Docker volume sharing with geoipupdate service for database access
• Configurable paths for MaxMind database directory

Performance Considerations

• Database connection pooling for efficient MaxMind database access
• Response caching for frequently queried IPs (optional optimization)
• Async request handling for batch operations

Success Metrics

Performance Metrics

1. API Response Time - 95% of requests processed under 200ms
2. Service Uptime - 99.9% availability for health checks
3. Error Rate - Less than 1% of requests result in 5xx errors

Usage Metrics

4. Successful Lookup Rate - 95% of valid IP requests return location data
5. API Request Volume - Track daily/monthly request counts
6. Batch vs Single Request Ratio - Monitor usage patterns

Health Indicators

7. Database Connectivity - Continuous access to MaxMind databases
8. Memory Usage - Stable memory consumption under normal load
9. Rate Limiting Effectiveness - Protection against abuse while serving legitimate requests

Open Questions

1. Map Provider Selection - Which specific free map provider should be implemented? (OpenStreetMap via Leaflet.js recommended)
2. API Key Management - Should there be an admin interface for managing API keys, or will they remain environment variable-based?
3. Caching Strategy - Should we implement response caching for performance optimization?
4. Database Update Handling - How should the service handle MaxMind database updates from the geoipupdate service?
5. Monitoring Integration - Beyond Seq logging, are there other monitoring tools to integrate with?
6. IPv6 Support - Should the service fully support IPv6 addresses from the start?
7. API Versioning - Should we implement API versioning for future compatibility?

---

Document Version: 1.0
Created: July 24, 2025
Target Audience: Junior Developer
Implementation Priority: High