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-12T10: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 uses MaxMind GeoLite2-City and GeoLite2-ASN databases to provide comprehensive IP geolocation with detailed information including country, continent, region, city, coordinates, timezone, postal codes, EU membership status, ISP organization, and autonomous system numbers (ASN). Official client libraries are available for .NET developers via the Bitip.Client NuGet package and for Node.js/TypeScript developers via the @flare/bitip-client npm package."
    },
    {
      "title": "Client Libraries",
      "items": [
        "**.NET / C# - Bitip.Client** - Official NuGet package with strongly-typed models, async/await support, and dependency injection integration. Includes comprehensive IntelliSense documentation and 40 unit/integration tests for reliability.",
        "**Node.js / TypeScript - @flare/bitip-client** - Official npm package with full TypeScript support, dual module format (CommonJS + ESM), and modern async/await API. Includes IP validation, request cancellation, and 33 comprehensive tests for reliability.",
        "**REST API** - Direct HTTP access available for any programming language with full OpenAPI/Swagger documentation"
      ]
    },
    {
      "title": "Core Features",
      "items": [
        "**Single IP Lookup** - Get geolocation data for individual IP addresses with detailed information including country, continent, region, city, coordinates, timezone, postal code, EU membership, ISP organization, and ASN",
        "**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 and GeoLite2-ASN databases",
        "**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, continent, region (with ISO codes), city, coordinates, timezone, postal code, EU membership status, ISP organization, and ASN",
            "Supports both IPv4 and IPv6 addresses",
            "Returns detailed location hierarchy with ISO codes and network information"
          ]
        },
        {
          "subtitle": "Detailed IP Lookup",
          "items": [
            "Endpoint: `GET /api/lookup/detailed?ip=:ip`",
            "Returns structured geolocation data with separate location and ASN sections",
            "Response format: `{ip, location: {...}, asn: {...}}`",
            "Location section includes all geographic data (country, region, city, coordinates, timezone, postal code)",
            "ASN section includes organization and autonomous system number",
            "Useful for applications requiring clear separation of geographic and network information"
          ]
        },
        {
          "subtitle": "Batch IP Lookup",
          "items": [
            "Endpoint: `POST /api/lookup/batch`",
            "Process up to 100 IP addresses in a single request",
            "Returns `{succeeded: IpLocation[], failed: Array<{ip, error}>}` with separated success and failure arrays",
            "Efficient bulk processing for large-scale operations",
            "Individual error handling for each IP address with clear error messages"
          ]
        },
        {
          "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 both **MaxMind GeoLite2-City** and **MaxMind GeoLite2-ASN** databases, which provide accurate geolocation and network data for millions of IP addresses worldwide. The databases are updated regularly by MaxMind and include information about countries, continents, regions, cities, coordinates, postal codes, time zones, EU membership status, ISP organizations, and autonomous system numbers. 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 **source-available software** with a proprietary license. The source code is publicly available for inspection and analysis, but commercial use, redistribution, and modifications require explicit written approval from Tudor Stanciu. A 30-day evaluation period is provided for testing and evaluation purposes. All rights are reserved by Tudor Stanciu. See the LICENSE file for complete terms and conditions, or contact tudor.stanciu94@gmail.com for licensing inquiries."
    }
  ]
}