# 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

## Implementation Decisions

Based on requirements clarification, the following decisions have been made:

1. **Map Provider**: OpenStreetMap via Leaflet.js will be used for both static preview and interactive maps
2. **API Key Management**: Environment variable-based configuration (admin interface may be added in future versions)
3. **Caching Strategy**: Simple in-memory caching will be implemented if straightforward, otherwise omitted for initial version
4. **Database Updates**: Service will return "Under maintenance, try again later" error during MaxMind database updates
5. **Monitoring**: Seq logging only for initial version
6. **IPv6 Support**: Will be included if MaxMind supports it and implementation is straightforward
7. **API Versioning**: Not implemented in initial version

---

**Document Version**: 1.1  
**Created**: July 24, 2025  
**Updated**: July 24, 2025  
**Target Audience**: Junior Developer  
**Implementation Priority**: High