mirror of
https://dev.azure.com/tstanciu94/PhantomMind/_git/Bitip
synced 2025-10-13 01:52:19 +03:00
345ed9c68c
- feat: Implement GeoIP lookup service with frontend interface - feat: Add dotenv dependency and configure environment variables; update rate limiter response handling - refactor: Remove development Dockerfile and docker-compose for streamlined setup; update GeoIP service to use new MaxMind types - chore: update dependencies and ESLint configuration - feat: Add documentation for breaking changes and package updates after major version upgrades - feat: Add environment configuration files and update module imports for ES module support - feat: Update nodemon configuration and add register script for ES module support - feat: Add .gitattributes file to enforce LF line endings and define text/binary file types - feat: Implement graceful shutdown with timeout and update nodemon configuration - feat: Update environment configuration and add detailed configuration guide - feat: add frontend origin validation and update rate limits - feat: add versioning arguments and detailed OCI image labels to Dockerfile - feat: add version and release notes endpoints, update frontend to display release notes - feat: Refactor App component to use React Router for navigation - feat: Update navigation styles and remove unused type definitions for react-router-dom - feat: Generate runtime configuration for frontend and serve env.js - feat: Update dependencies, enhance ESLint configuration, and improve Vite setup - refactor: Remove ensureTrailingSlash function and simplify basePath assignment in Vite config
164 lines
8.2 KiB
Markdown
164 lines
8.2 KiB
Markdown
# 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
|