bitip/content/Overview.json

{
  "title": "Bitip - Professional GeoIP Lookup Service",
  "subtitle": "Modern GeoIP lookup service with REST API and interactive web interface",
  "lastUpdated": "2025-10-05T14:00:00Z",
  "sections": [
    {
      "title": "Overview",
      "content": "Bitip is a high-performance GeoIP lookup service designed to provide accurate geolocation data for IP addresses. Built with modern web technologies, it offers both a RESTful API for programmatic access and an intuitive web interface for interactive lookups. The service is built on the reliable MaxMind GeoLite2 database and provides real-time IP geolocation with detailed information including country, city, coordinates, timezone, and postal codes."
    },
    {
      "title": "Core Features",
      "items": [
        "**Single IP Lookup** - Get geolocation data for individual IP addresses with detailed information including country, city, coordinates, timezone, and postal code",
        "**Batch IP Lookup** - Process up to 100 IP addresses in a single request for efficient bulk operations",
        "**Dual API Access** - Separate authentication for frontend and external API consumers with different rate limiting profiles",
        "**Origin Validation** - Security layer that validates request origins for frontend API keys to prevent unauthorized access",
        "**Rate Limiting** - Configurable request limits per API key type (100 req/min for frontend, 1000 req/min for external)",
        "**Real-time Lookup** - Instant geolocation results powered by MaxMind GeoLite2 City database",
        "**Interactive Web UI** - Modern, responsive interface for manual IP lookups with visual feedback and interactive maps",
        "**RESTful API** - Clean, well-documented API endpoints for easy integration into your applications",
        "**Docker Support** - Containerized deployment with Docker for easy setup and scalability",
        "**Production Ready** - Includes logging, error handling, security middleware, and monitoring capabilities"
      ]
    },
    {
      "title": "Technology Stack",
      "subsections": [
        {
          "subtitle": "Backend",
          "items": [
            "**Node.js 18+** with ES Modules (ESM) for modern JavaScript features",
            "**Express 5.x** - Fast, minimalist web framework with enhanced routing capabilities",
            "**TypeScript 5.x** - Type-safe development with latest language features and compile-time checking",
            "**tsup** - Modern bundler built on esbuild for 10x faster builds (~88ms) and cleaner imports without .js extensions",
            "**MaxMind GeoIP2 Node.js API** - Official MaxMind library for GeoLite2 database integration",
            "**express-rate-limit 8.x** - Advanced rate limiting with IP tracking and customizable limits",
            "**Helmet** - Security middleware that sets various HTTP headers to protect Express applications",
            "**CORS** - Cross-Origin Resource Sharing support for secure cross-domain requests",
            "**Joi** - Schema validation for API request validation and error handling",
            "**Seq Logging** (optional) - Structured logging for production monitoring and debugging",
            "**node-cache** - In-memory caching layer for improved performance"
          ]
        },
        {
          "subtitle": "Frontend",
          "items": [
            "**React 19.x** - Modern UI library with latest features and improved performance",
            "**TypeScript** - Type-safe frontend development with IntelliSense support",
            "**Vite 7.x** - Next-generation frontend tooling with lightning-fast HMR and optimized builds",
            "**Axios** - Promise-based HTTP client for API requests with interceptors",
            "**Leaflet & React-Leaflet** - Interactive map components for visualizing IP locations",
            "**React Router 7.x** - Client-side routing for single-page application navigation",
            "**CSS Modules** - Scoped styling with modern CSS features"
          ]
        },
        {
          "subtitle": "Infrastructure",
          "items": [
            "**Docker** - Container platform for consistent deployment across environments",
            "**Multi-stage Docker builds** - Optimized image size with separate build and runtime stages",
            "**npm workspaces** - Monorepo structure for managing frontend and backend together",
            "**ESLint & Prettier** - Code quality and formatting tools for consistent code style"
          ]
        }
      ]
    },
    {
      "title": "API Capabilities",
      "subsections": [
        {
          "subtitle": "Single IP Lookup",
          "items": [
            "Endpoint: `GET /api/lookup/:ip`",
            "Returns comprehensive geolocation data for a single IP address",
            "Includes country, region, city, coordinates, timezone, and postal code",
            "Supports both IPv4 and IPv6 addresses",
            "Returns detailed location hierarchy with ISO codes"
          ]
        },
        {
          "subtitle": "Batch IP Lookup",
          "items": [
            "Endpoint: `POST /api/lookup/batch`",
            "Process up to 100 IP addresses in a single request",
            "Returns array of results matching input order",
            "Efficient bulk processing for large-scale operations",
            "Individual error handling for each IP address"
          ]
        },
        {
          "subtitle": "Current IP Detection",
          "items": [
            "Endpoint: `GET /api/ip`",
            "Automatically detects and returns the requester's IP address",
            "Useful for self-lookup functionality",
            "Handles proxy headers (X-Forwarded-For, X-Real-IP)",
            "Returns clean IP address without additional data"
          ]
        },
        {
          "subtitle": "Version Information",
          "items": [
            "Endpoint: `GET /api/version`",
            "Returns application version, build date, and git revision",
            "Useful for monitoring and debugging deployments",
            "Includes service name and metadata"
          ]
        },
        {
          "subtitle": "Release Notes",
          "items": [
            "Endpoint: `GET /api/release-notes`",
            "Returns detailed release notes for all versions",
            "Structured JSON format with sections and subsections",
            "Includes version history, features, and changes"
          ]
        },
        {
          "subtitle": "Overview",
          "items": [
            "Endpoint: `GET /api/overview`",
            "Returns comprehensive application overview",
            "Includes current features, technologies, and capabilities",
            "Always up-to-date system presentation"
          ]
        }
      ]
    },
    {
      "title": "Security Features",
      "items": [
        "**API Key Authentication** - Separate keys for frontend and external API access with configurable permissions",
        "**Origin Validation** - Validates request origins for frontend API keys to prevent unauthorized domain usage",
        "**Rate Limiting** - Prevents abuse with configurable limits per API key type (100/min frontend, 1000/min external)",
        "**Helmet Security Headers** - Automatically sets secure HTTP headers (X-Frame-Options, X-Content-Type-Options, etc.)",
        "**CORS Configuration** - Configurable cross-origin policies with whitelist support",
        "**Input Validation** - Joi schema validation for all API requests to prevent injection attacks",
        "**Error Handling** - Sanitized error messages that don't expose internal system details",
        "**Docker Isolation** - Containerized environment with minimal attack surface"
      ]
    },
    {
      "title": "Deployment Options",
      "subsections": [
        {
          "subtitle": "Docker Deployment",
          "items": [
            "Pre-built Docker image with optimized multi-stage build",
            "Single command deployment: `docker run -p 3100:3100 bitip`",
            "Environment-based configuration via `.env` file",
            "Health check endpoints for container orchestration",
            "Volume mounting for GeoLite2 database updates"
          ]
        },
        {
          "subtitle": "Development Setup",
          "items": [
            "npm workspaces for managing monorepo structure",
            "Hot module replacement with Vite for fast development",
            "Nodemon for backend auto-restart on changes",
            "TypeScript compilation with watch mode",
            "Concurrent frontend and backend development servers"
          ]
        },
        {
          "subtitle": "Production Deployment",
          "items": [
            "Production-optimized build with code splitting",
            "Static asset serving from Express backend",
            "Structured logging with Seq integration (optional)",
            "Environment-specific configuration management",
            "Graceful shutdown with timeout handling"
          ]
        }
      ]
    },
    {
      "title": "Use Cases",
      "items": [
        "**Fraud Detection** - Identify suspicious IP addresses and detect geographic anomalies in user behavior",
        "**Content Localization** - Serve region-specific content based on user location",
        "**Analytics & Reporting** - Track geographic distribution of website visitors and API users",
        "**Access Control** - Implement geo-blocking or geo-fencing for restricted content",
        "**Network Diagnostics** - Debug network issues and trace IP address origins",
        "**Compliance** - Ensure data residency requirements and regional regulations are met",
        "**Marketing Intelligence** - Analyze customer geographic distribution for targeted campaigns",
        "**Security Monitoring** - Monitor login attempts and API requests from different locations"
      ]
    },
    {
      "title": "Performance & Scalability",
      "items": [
        "**In-Memory Database** - MaxMind GeoLite2 loaded in memory for sub-millisecond lookups",
        "**Caching Layer** - Optional result caching with configurable TTL",
        "**Batch Processing** - Efficient bulk lookup with up to 100 IPs per request",
        "**Lightweight Architecture** - Minimal dependencies for fast startup and low memory footprint",
        "**Horizontal Scaling** - Stateless design allows multiple instances behind load balancer",
        "**Docker Optimization** - Multi-stage builds with minimal production image size",
        "**Zero External Dependencies** - No database connections or external service calls during lookup"
      ]
    },
    {
      "title": "Configuration & Customization",
      "items": [
        "**Environment Variables** - All configuration via `.env` file for easy deployment",
        "**Configurable Rate Limits** - Adjust per API key type based on your needs",
        "**Custom API Keys** - Define multiple API keys with different access levels",
        "**Origin Whitelisting** - Control which domains can use frontend API keys",
        "**HTTPS Security Headers** - Toggle security headers (CSP, HSTS, COOP, CORP) based on deployment type (HTTP vs HTTPS)",
        "**Port Configuration** - Customize backend and frontend ports",
        "**Base Path Support** - Deploy under custom URL paths for reverse proxy scenarios",
        "**Configurable Logging Levels** - Hierarchical log filtering (debug, info, warning, error) similar to Serilog in .NET",
        "**Seq Integration** - Optional structured logging to Seq server with configurable minimum level",
        "**Database Path** - Configurable GeoLite2 database location"
      ]
    },
    {
      "title": "Monitoring & Observability",
      "items": [
        "**Structured Logging** - JSON-formatted logs with context and correlation IDs",
        "**Hierarchical Log Levels** - Configurable minimum log level (debug, info, warning, error) for filtering",
        "**Version Endpoint** - Check deployed version, build date, and git revision",
        "**Health Checks** - Monitor service availability and database status",
        "**Error Tracking** - Detailed error messages with stack traces in development",
        "**Request Logging** - Log all API requests with IP, method, path, and response time",
        "**Rate Limit Metrics** - Track rate limit hits and blocked requests",
        "**Seq Integration** - Optional centralized logging with query and dashboard capabilities",
        "**Production-Ready Logging** - Minimal overhead with filtered log levels for production environments"
      ]
    },
    {
      "title": "Data Sources",
      "content": "Bitip uses the **MaxMind GeoLite2 City** database, which provides accurate geolocation data for millions of IP addresses worldwide. The database is updated regularly by MaxMind and includes information about countries, regions, cities, coordinates, postal codes, and time zones. While GeoLite2 is a free version with good accuracy, MaxMind also offers premium databases with higher accuracy and additional data points for commercial applications."
    },
    {
      "title": "License",
      "content": "Bitip is **proprietary software** licensed under a custom license. The software is not open source and all rights are reserved by Tudor Stanciu. A 30-day evaluation period is provided for testing purposes. Commercial use, redistribution, and modifications require explicit written approval. See the LICENSE file for complete terms and conditions, or contact tudor.stanciu94@gmail.com for licensing inquiries."
    }
  ]
}