bitip/content/ReleaseNotes.json

{
  "releases": [
    {
      "version": "1.1.3",
      "date": "2025-10-12T10:00:00Z",
      "title": "IP Validation Improvements & Node.js Client Library",
      "summary": "Replaced custom regex-based IP validation with Node.js built-in net.isIP() for improved accuracy and IPv6 support. Released official @flare/bitip-client npm package (v1.0.0) for TypeScript/Node.js developers.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.1.3 improves IP validation reliability by adopting Node.js built-in net.isIP() function, which provides comprehensive IPv4 and IPv6 validation including compressed formats. Additionally, this release introduces the official @flare/bitip-client npm package, bringing first-class TypeScript/Node.js support to complement the existing .NET client library."
        },
        {
          "title": "IP Validation Improvements",
          "items": [
            "**Node.js Built-in Validation** - Replaced complex regex patterns with net.isIP() function",
            "**Enhanced IPv6 Support** - Now validates all IPv6 formats including compressed (::1, fe80::1), standard, and IPv4-mapped addresses",
            "**Backend & Client Sync** - Consistent validation logic across backend service and Node.js client library",
            "**Improved Accuracy** - Leverages battle-tested C++ binding from Node.js core for maximum reliability",
            "**Smaller Bundle Size** - Node.js client reduced from 8.87 KB to 8.15 KB (-8%) by removing regex code",
            "**Zero Dependencies** - Uses Node.js built-in module, no external packages required"
          ]
        },
        {
          "title": "Node.js Client Library (@flare/bitip-client v1.0.0)",
          "items": [
            "**Official npm Package** - Published to @flare scope on custom npm registry",
            "**TypeScript First** - Full type definitions and IntelliSense support",
            "**Dual Module Format** - CommonJS and ESM exports for maximum compatibility",
            "**Async/Await API** - Modern promise-based interface with AbortSignal cancellation",
            "**Comprehensive Testing** - 19 passing tests with 100% coverage of core functionality",
            "**Professional Documentation** - README with installation guide, usage examples, and API reference",
            "**Minimal Dependencies** - Only requires axios for HTTP requests",
            "**Tree-shakeable** - Optimized bundle with dead code elimination"
          ]
        },
        {
          "title": "Node.js Client Features",
          "items": [
            "**BitipClient Class** - Clean object-oriented API for all endpoints",
            "**Five Core Methods** - getHealth(), getVersion(), getIpLocation(), getDetailedIpLocation(), getBatchIpLocation()",
            "**Built-in IP Validation** - Client-side validation using net.isIP() before API calls",
            "**Error Aggregation** - Batch operations combine client validation errors with API errors",
            "**Request Cancellation** - Full AbortSignal support for timeout and cancellation scenarios",
            "**URL Normalization** - Automatic base URL formatting and trailing slash handling",
            "**Professional Packaging** - Includes LICENSE, CHANGELOG, comprehensive README, and release guide"
          ]
        },
        {
          "title": "Backend Changes",
          "items": [
            "**Updated geoip.ts** - isValidIP() now uses net.isIP() instead of custom regex",
            "**Enhanced Documentation** - Added JSDoc comments explaining supported IP formats",
            "**Backward Compatible** - API behavior unchanged, only internal validation improved"
          ]
        },
        {
          "title": "Installation & Usage",
          "content": "Install via npm with `npm install @flare/bitip-client`. Import and instantiate the client with your Bitip API base URL and API key. The package exports TypeScript types for all request/response models. See the package README for complete examples and API documentation."
        },
        {
          "title": "Developer Experience",
          "items": [
            "**Zero Configuration Complexity** - Simple setup with just base URL and API key",
            "**IDE Support** - Full autocomplete and type checking in VS Code, WebStorm, etc.",
            "**Example Code** - Comprehensive examples for all methods in README",
            "**Vitest Test Suite** - Modern testing setup with coverage reporting",
            "**ESLint & Prettier** - Code quality tools configured out of the box"
          ]
        }
      ]
    },
    {
      "version": "1.1.2",
      "date": "2025-10-09T16:00:00Z",
      "title": "Batch API Refactoring & .NET Client Completion",
      "summary": "Refactored batch lookup API to use a cleaner succeeded/failed response structure instead of union types. Completed .NET client library (Bitip.Client v1.0.0) with full batch lookup support, comprehensive testing, and updated documentation.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.1.2 introduces a breaking change to the batch lookup API for improved clarity and type safety. The response structure now separates successful and failed lookups into distinct arrays, making it easier to process results and handle errors. The .NET client library has been completed with full batch lookup support and is ready for v1.0.0 release."
        },
        {
          "title": "⚠️ Breaking Changes - Batch API",
          "items": [
            "**New Response Structure** - `/api/lookup/batch` now returns `{succeeded: IpLocation[], failed: Array<{ip, error}>}` instead of `{results: Array<IpLocation | {ip, error}>}`",
            "**Separated Collections** - Successful lookups are in the `succeeded` array, failures in the `failed` array",
            "**Type Safety** - Eliminates union types for cleaner, more predictable response handling",
            "**Consistent Error Format** - All errors (validation, API failures) use the same `{ip, error}` structure",
            "**Better Iteration** - Process successful and failed lookups independently without type checks"
          ]
        },
        {
          "title": "Backend Improvements",
          "items": [
            "**TypeScript Type Refactoring** - Updated `BatchGeoIPResponse` interface with `succeeded` and `failed` properties",
            "**Service Layer Updates** - Modified `lookupBatch()` in `geoip.ts` to return separated results",
            "**Route Handler Changes** - Updated batch endpoint to combine API failures and validation errors in `failed` array",
            "**Private IP Handling** - Private/reserved IPs rejected with clear error messages in `failed` array",
            "**Promise.allSettled** - Used for parallel lookups with proper error handling"
          ]
        },
        {
          "title": ".NET Client Completion (v1.0.0)",
          "items": [
            "**Batch Lookup Implementation** - Added `GetBatchIpLocation()` method to `IBitipClient` interface",
            "**Clean Model Design** - `BatchIpLookupResponse` with `IEnumerable<IpLocation> Succeeded` and `IEnumerable<BatchIpLookupError> Failed`",
            "**No Model Pollution** - Kept `IpLocation` strongly-typed without nullable properties for batch use",
            "**BatchIpLookupError Record** - Dedicated record type with `string Ip` and `string Error` properties",
            "**Client-Side Validation** - Added `IpValidator.IsValid()` helper to validate IPs before API call",
            "**Error Aggregation** - Combines client-side validation errors with API errors in unified response"
          ]
        },
        {
          "title": "Testing & Quality",
          "items": [
            "**40 Tests Passing** - Complete test suite with unit and integration tests",
            "**GetBatchIpLocationTests** - 10 comprehensive tests covering all batch scenarios",
            "**Mixed Success/Failure Handling** - Tests verify both succeeded and failed collections populate correctly",
            "**Invalid IP Handling** - Tests confirm client-side validation catches malformed IPs",
            "**Cancellation Token Support** - Tests verify proper async cancellation behavior",
            "**Integration Tests** - Real API tests confirm end-to-end batch functionality"
          ]
        },
        {
          "title": "Documentation Updates",
          "items": [
            "**Bitip.Client README** - Updated with new batch API structure and code examples",
            "**Separate Loop Examples** - Shows iteration over `Succeeded` and `Failed` collections independently",
            "**Clear Error Messages** - Documents that invalid IPs are validated client-side with descriptive errors",
            "**Migration Guide** - Inline comments explain the API structure change for existing users",
            "**Type Safety Benefits** - Documentation highlights improved type safety with separated arrays"
          ]
        },
        {
          "title": "Developer Experience",
          "items": [
            "**Clearer API Contract** - No more union types or type guards needed when processing results",
            "**Predictable Responses** - Always get both `succeeded` and `failed` arrays (may be empty)",
            "**Better IntelliSense** - IDEs provide better autocomplete with distinct types",
            "**Easier Error Handling** - Loop through `failed` array without type checking each item",
            "**Maintainability** - Code is more readable and easier to test with explicit separation"
          ]
        },
        {
          "title": "Migration Notes",
          "content": "If you are using the batch lookup API, update your code to access `response.succeeded` instead of filtering `response.results`. Failed lookups are now in `response.failed` array. For .NET developers using Bitip.Client, update to v1.0.0 and access `Succeeded` and `Failed` properties on the `BatchIpLookupResponse` object."
        }
      ]
    },
    {
      "version": "1.1.1",
      "date": "2025-10-09T12:00:00Z",
      "title": ".NET Client Library & API Refinements",
      "summary": "Introduced the official Bitip.Client NuGet package for .NET developers, providing a strongly-typed, async-first client library. Also refined API response properties for better clarity and consistency.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.1.1 brings first-class .NET support to Bitip with the release of the official Bitip.Client library on NuGet. This release also includes API refinements to improve property naming consistency and clarity across all endpoints."
        },
        {
          "title": "New .NET Client Library",
          "items": [
            "**Bitip.Client NuGet Package** - Official .NET client library for easy integration",
            "**Strongly-Typed Models** - Full IntelliSense support with typed request/response models",
            "**Async/Await Support** - Modern async-first API with CancellationToken support",
            "**Dependency Injection Ready** - Seamless integration with Microsoft.Extensions.DependencyInjection",
            "**Comprehensive Testing** - 29 unit and integration tests ensuring reliability",
            "**MIT Licensed** - Free and open-source for unrestricted use",
            "**Complete Documentation** - README with installation guide, usage examples, and error handling patterns"
          ]
        },
        {
          "title": "API Refinements",
          "items": [
            "**Version Endpoint** - Renamed `createdAt` to `buildDate` for clarity in `/version` response",
            "**Version Endpoint** - Renamed `gitRevision` to `commitHash` for consistency in `/version` response",
            "**Detailed Lookup** - Added dedicated `asn` section in `/lookup/detailed` response for better structure",
            "**Property Consistency** - Standardized naming conventions across all API endpoints",
            "**Backward Compatible** - Changes maintain compatibility with existing integrations"
          ]
        },
        {
          "title": ".NET Client Features",
          "items": [
            "**IBitipClient Interface** - Clean abstraction for dependency injection and testing",
            "**Four Core Methods** - GetHealth(), GetVersion(), GetIpLocation(), GetDetailedIpLocation()",
            "**Automatic Serialization** - JSON serialization handled transparently",
            "**HTTP Client Factory** - Uses IHttpClientFactory for efficient connection management",
            "**Error Handling** - Typed exceptions with detailed error messages",
            "**IPv4 & IPv6 Support** - Full support for both IP address formats",
            "**Validation Built-in** - Client-side IP validation before API calls"
          ]
        },
        {
          "title": "Installation & Usage",
          "content": "Install via NuGet Package Manager or .NET CLI with `dotnet add package Bitip.Client`. Register services in your DI container using `services.UseBitipClient(baseUrl, apiKey)`, then inject `IBitipClient` into your classes. See the package README for complete examples and documentation."
        },
        {
          "title": "Developer Experience",
          "items": [
            "**Zero Configuration** - Simple setup with just base URL and API key",
            "**IntelliSense Support** - Full IDE autocomplete and documentation tooltips",
            "**Example Projects** - Sample code demonstrating all features",
            "**Test Helpers** - Comprehensive test fixtures for unit testing your code",
            "**Active Maintenance** - Regular updates and responsive issue tracking"
          ]
        }
      ]
    },
    {
      "version": "1.1.0",
      "date": "2025-10-06T10:00:00Z",
      "title": "Enhanced GeoIP Data - ASN & Network Information",
      "summary": "Added comprehensive network and geographic data by integrating MaxMind GeoLite2-ASN database alongside the existing City database. IP lookups now include ISP organization, ASN, continent information, region codes, and EU membership status.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.1.0 significantly expands the geolocation data provided by Bitip. By integrating the MaxMind GeoLite2-ASN database alongside the existing City database, the service now provides comprehensive network information including ISP organizations, autonomous system numbers (ASN), continent details, region ISO codes, and EU membership status. This enhancement makes Bitip more valuable for network diagnostics, fraud detection, and compliance use cases."
        },
        {
          "title": "New Data Fields",
          "items": [
            "**EU Membership Status** - Boolean flag indicating if the IP's country is in the European Union",
            "**Continent Information** - Continent name and ISO code (e.g., 'North America', 'NA')",
            "**Region ISO Codes** - Standardized region/subdivision codes alongside names (e.g., 'California', 'CA')",
            "**ISP Organization** - Name of the organization operating the autonomous system (e.g., 'Google LLC')",
            "**Autonomous System Number (ASN)** - Network identifier for routing and network analysis (e.g., AS15169)"
          ]
        },
        {
          "title": "Backend Enhancements",
          "items": [
            "**Dual Database Integration** - Added GeoLite2-ASN.mmdb reader alongside GeoLite2-City.mmdb",
            "**Mandatory ASN Database** - Both databases are now required for service initialization",
            "**Enhanced Type Definitions** - Updated TypeScript interfaces to include all new fields",
            "**Merged Query Results** - Single API call queries both databases and merges results seamlessly",
            "**Backward Compatible** - Existing API endpoints return enhanced data without breaking changes"
          ]
        },
        {
          "title": "Frontend Updates",
          "items": [
            "**Enhanced UI Display** - All new fields visible in the web interface lookup results",
            "**Improved Data Presentation** - Region and continent shown with ISO codes for clarity",
            "**Network Information Section** - ISP organization and ASN displayed prominently",
            "**EU Indicator** - Clear Yes/No display for European Union membership status",
            "**Type Safety** - Frontend TypeScript types updated to match backend response structure"
          ]
        },
        {
          "title": "Documentation Updates",
          "items": [
            "**README.md** - Updated API response examples with all new fields",
            "**Database Requirements** - Documentation now specifies both GeoLite2-City and GeoLite2-ASN are required",
            "**Setup Instructions** - Updated manual download and geoipupdate configuration guides",
            "**Overview.json** - Enhanced feature descriptions and data source information",
            "**API Documentation** - All endpoint examples reflect expanded response structure"
          ]
        },
        {
          "title": "Use Case Benefits",
          "items": [
            "**Network Diagnostics** - ASN and organization data helps identify network routing and ISP information",
            "**Fraud Detection** - Enhanced geographic and network data improves anomaly detection capabilities",
            "**Compliance** - EU membership status aids GDPR and data residency compliance checks",
            "**Analytics** - Continent and region codes enable better geographic grouping and reporting",
            "**Security Monitoring** - ISP and ASN data provides additional context for access analysis"
          ]
        }
      ]
    },
    {
      "version": "1.0.4",
      "date": "2025-10-05T20:30:00Z",
      "title": "Dependency Optimization - @flare/utiliyo Integration",
      "summary": "Replaced local pathCombine utility with battle-tested @flare/utiliyo package, reducing code duplication and leveraging shared utilities.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.0.4 optimizes frontend dependencies by integrating @flare/utiliyo, a shared utility package from the @flare ecosystem. This change eliminates duplicate code by replacing the local pathCombine implementation with a well-tested, maintained alternative from the custom npm registry."
        },
        {
          "title": "Dependency Management",
          "items": [
            "**@flare/utiliyo Integration** - Added @flare/utiliyo v1.2.2 as frontend dependency",
            "**Custom Registry Configuration** - Configured .npmrc for @flare scoped packages",
            "**Code Deduplication** - Removed local pathCombine implementation (33 lines)",
            "**Shared Utilities** - Leverages battle-tested path manipulation utilities"
          ]
        },
        {
          "title": "Technical Changes",
          "items": [
            "Added `.npmrc` in project root with `@flare:registry=https://lab.code-rove.com/public-node-registry`",
            "Updated frontend package.json with `@flare/utiliyo: ^1.2.2` dependency"
          ]
        },
        {
          "title": "Benefits",
          "items": [
            "**Reduced Maintenance** - No need to maintain local path utilities",
            "**Bug Fixes** - Automatic bug fixes from upstream package updates",
            "**Feature Updates** - Access to new utilities as they're added",
            "**Consistency** - Same path handling across multiple @flare projects",
            "**Testing** - Leverages comprehensive test suite from utiliyo package"
          ]
        }
      ]
    },
    {
      "version": "1.0.3",
      "date": "2025-10-05T16:30:00Z",
      "title": "Branding & Visual Identity",
      "summary": "Added favicon and logo to enhance the application's visual identity and brand recognition.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.0.3 introduces visual branding elements to the application. The new favicon provides easy tab identification in the browser, while the logo in the header reinforces the application's identity and creates a more polished, professional appearance."
        },
        {
          "title": "Visual Enhancements",
          "items": [
            "**Favicon** - Custom favicon displays in browser tabs and bookmarks for easy identification",
            "**Header Logo** - Bitip logo appears in the application header for brand recognition",
            "**Consistent Branding** - Visual elements maintain cohesive design language",
            "**Professional Appearance** - Polished look with branded assets throughout the UI",
            "**Base Path Support** - Logo and favicon URLs respect configured base path for flexible deployment"
          ]
        },
        {
          "title": "Technical Implementation",
          "items": [
            "Added `favicon.png` to `src/frontend/public/` directory",
            "Added `logo.png` to `src/frontend/public/` directory",
            "Updated `index.html` with favicon link using `%BASE_URL%` placeholder",
            "Integrated logo in `App.tsx` header with `config.BASE_PATH` for dynamic path resolution",
            "Vite automatically replaces `%BASE_URL%` at build time for correct asset paths",
            "Both assets served from public directory in development and production builds"
          ]
        },
        {
          "title": "Asset Details",
          "items": [
            "**Favicon Format** - PNG format with standard dimensions for browser compatibility",
            "**Logo Placement** - Positioned prominently in application header",
            "**Path Handling** - Uses environment-aware BASE_PATH configuration",
            "**Build Process** - Assets copied to dist during production build",
            "**Static Serving** - Backend serves public assets correctly in both dev and prod modes"
          ]
        }
      ]
    },
    {
      "version": "1.0.2",
      "date": "2025-10-05T15:00:00Z",
      "title": "External Resources & Links",
      "summary": "Added external resource links in the UI footer for easy access to repository, documentation, Docker registry, and client libraries.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.0.2 enhances the user interface by adding quick access links to external resources. Users can now easily navigate to the source code repository, documentation, Docker registry, and official client libraries directly from the application footer."
        },
        {
          "title": "UI Enhancements",
          "items": [
            "**Resource Links Footer** - Added prominent footer section with external resource links",
            "**Icon-based Navigation** - Each link includes relevant emoji icon for visual identification",
            "**Hover Effects** - Smooth hover animations with background highlight and lift effect",
            "**Responsive Layout** - Links wrap gracefully on smaller screens",
            "**Clean Design** - Subtle styling that complements existing footer aesthetic"
          ]
        },
        {
          "title": "Available Resources",
          "items": [
            "**📦 Repository** - Source code hosted on Gitea (lab.code-rove.com)",
            "**📖 Documentation** - Comprehensive README and project documentation",
            "**🐳 Docker** - Official Docker images on ProGet container registry",
            "**📦 NuGet** - .NET client library for C# applications",
            "**📦 NPM** - JavaScript/TypeScript client library (@flare/bitip-client)"
          ]
        },
        {
          "title": "Technical Details",
          "items": [
            "Added `.footer-links` CSS class with flexbox layout",
            "Implemented smooth hover transitions with `transform` and `background` effects",
            "Links open in new tab with `target=\"_blank\"` and security attributes",
            "Added descriptive `title` attributes for accessibility",
            "Maintained consistent spacing and typography with existing footer"
          ]
        }
      ]
    },
    {
      "version": "1.0.1",
      "date": "2025-10-05T02:29:00Z",
      "title": "Build System Modernization - tsup Migration",
      "summary": "Migrated backend build system from tsc to tsup for cleaner imports, faster builds, and improved developer experience.",
      "sections": [
        {
          "title": "Overview",
          "content": "Version 1.0.1 brings significant improvements to the backend build system by migrating from TypeScript Compiler (tsc) to tsup, a modern bundler built on esbuild. This change eliminates the need for .js extensions in imports and provides faster build times with optimized bundling."
        },
        {
          "title": "Build System Improvements",
          "items": [
            "**Migrated to tsup** - Modern bundler for backend with esbuild performance",
            "**Cleaner imports** - No more `.js` extensions required in TypeScript imports",
            "**Faster builds** - ~10x faster build times (82ms vs ~1000ms with tsc)",
            "**Single bundle output** - One optimized `index.js` file for production",
            "**Better DX** - Imports match source code exactly, no mental overhead",
            "**Sourcemaps included** - Full debugging support with accurate stack traces",
            "**Tree-shaking enabled** - Smaller bundle size with unused code elimination"
          ]
        },
        {
          "title": "Technical Changes",
          "items": [
            "Changed `moduleResolution` from `node` to `bundler` in tsconfig.json",
            "Removed all `.js` extensions from backend imports (handlers, middleware, routes, services)",
            "Added `tsup.config.ts` with optimized ESM output configuration",
            "Updated build script from `tsc` to `tsup` in package.json",
            "Created centralized path utilities in `src/backend/utils/paths.ts`",
            "Replaced duplicated `__dirname` logic with `resolveFromRoot()` function",
            "Path resolution now environment-aware (dev vs production)",
            "Maintained development mode with nodemon for hot-reload support"
          ]
        },
        {
          "title": "Benefits",
          "items": [
            "**Improved Developer Experience** - Write imports without file extensions, matching frontend patterns",
            "**Faster CI/CD Pipelines** - Reduced build time improves deployment speed",
            "**Smaller Production Bundle** - Single optimized file reduces startup overhead",
            "**Future-proof Tooling** - Modern bundler aligns with ecosystem trends (tRPC, Hono, Drizzle use tsup)",
            "**Maintained Compatibility** - ESM output unchanged, Docker builds work identically"
          ]
        },
        {
          "title": "Backward Compatibility",
          "content": "This is a build-time change only. The runtime behavior, API contracts, and deployment process remain unchanged. Docker images continue to work with the same environment variables and configuration."
        },
        {
          "title": "Migration Notes",
          "items": [
            "Frontend builds unchanged (Vite continues to handle bundling)",
            "No changes required to environment variables or deployment scripts",
            "Source code now has cleaner imports without `.js` extensions",
            "Build output is a single `dist/backend/index.js` instead of multiple files"
          ]
        }
      ]
    },
    {
      "version": "1.0.0",
      "date": "2025-10-01T12:00:00Z",
      "title": "Initial Release - Bitip GeoIP Service",
      "summary": "First production-ready release of Bitip, a modern GeoIP lookup service with REST API and interactive web interface.",
      "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."
        },
        {
          "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",
            "**RESTful API** - Clean, well-documented API endpoints for easy integration"
          ]
        },
        {
          "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",
                "**TypeScript 5.x** - Type-safe development with latest language features",
                "**MaxMind GeoIP2 Node.js API** - Official MaxMind library for GeoLite2 database integration",
                "**express-rate-limit 8.x** - Advanced rate limiting with IP tracking",
                "**Helmet** - Security middleware for Express applications",
                "**CORS** - Cross-Origin Resource Sharing support",
                "**Joi** - Schema validation for API requests",
                "**Seq Logging** (optional) - Structured logging for production monitoring",
                "**node-cache** - In-memory caching layer"
              ]
            },
            {
              "subtitle": "Frontend",
              "items": [
                "**React 19.x** - Modern UI library with latest features",
                "**TypeScript** - Type-safe frontend development",
                "**Vite 7.x** - Next-generation frontend tooling with lightning-fast HMR",
                "**Axios** - Promise-based HTTP client",
                "**React Leaflet** - Interactive maps for geolocation visualization",
                "**ESLint & Prettier** - Code quality and formatting"
              ]
            },
            {
              "subtitle": "Infrastructure",
              "items": [
                "**Docker** - Containerized deployment with multi-stage builds",
                "**Node.js Alpine** - Lightweight production images",
                "**Health Checks** - Container health monitoring",
                "**Graceful Shutdown** - Clean process termination",
                "**Non-root User** - Security-hardened container execution"
              ]
            }
          ]
        },
        {
          "title": "Security Features",
          "items": [
            "**API Key Authentication** - Two-tier authentication system (frontend + external)",
            "**Origin Validation** - Validates Origin/Referer headers for frontend API key requests",
            "**Rate Limiting** - Per-API-key request throttling with configurable windows",
            "**CORS Protection** - Configurable cross-origin resource sharing",
            "**Helmet Security Headers** - Standard HTTP security headers (CSP, HSTS, X-Frame-Options, etc.)",
            "**Input Validation** - Schema-based request validation with Joi",
            "**Error Sanitization** - Production mode hides sensitive error details"
          ]
        },
        {
          "title": "API Endpoints",
          "items": [
            "`GET /api/health` - Health check endpoint for monitoring",
            "`GET /api/ip` - Returns the client's public IP address",
            "`GET /api/lookup?ip={ip}` - Single IP geolocation lookup (simplified response)",
            "`GET /api/lookup/detailed?ip={ip}` - Detailed IP geolocation lookup (full MaxMind data)",
            "`POST /api/lookup/batch` - Batch IP lookup (up to 100 IPs per request)"
          ]
        },
        {
          "title": "Configuration",
          "items": [
            "**Environment-based Configuration** - All settings via `.env` file",
            "**Flexible Port Configuration** - Configurable API port (default: 5172)",
            "**Base Path Support** - Deploy under custom URL paths (e.g., `/geoip-ui`)",
            "**Database Path Configuration** - Custom MaxMind database locations",
            "**Rate Limit Tuning** - Separate limits for frontend and external consumers",
            "**Batch Size Limits** - Configurable maximum batch request size",
            "**Debounce Configuration** - Adjustable input debounce delays"
          ]
        },
        {
          "title": "Development Journey",
          "content": "Bitip was developed as a modern alternative to traditional GeoIP services, focusing on developer experience and deployment simplicity. The project was built from the ground up with TypeScript for type safety and maintainability. Special attention was given to security best practices, including origin validation and multi-tier API authentication. The ESM migration ensures compatibility with modern JavaScript ecosystems and future-proofs the codebase. All major dependencies were updated to their latest stable versions, with breaking changes carefully addressed and documented."
        },
        {
          "title": "Architecture Highlights",
          "items": [
            "**Multi-stage Docker Build** - Separate build stages for frontend, backend, and production",
            "**Graceful Shutdown** - Proper signal handling (SIGTERM, SIGINT, SIGUSR2) for zero-downtime deployments",
            "**Structured Logging** - JSON-formatted logs with optional Seq integration",
            "**Error Handling** - Global error handlers with environment-aware verbosity",
            "**Middleware Pipeline** - Layered request processing (logging, auth, rate limiting, CORS)",
            "**Type Safety** - End-to-end TypeScript for compile-time error detection"
          ]
        },
        {
          "title": "Known Limitations",
          "items": [
            "Requires external MaxMind GeoLite2 City database (not included)",
            "Frontend API key is visible in browser (mitigated by origin validation + aggressive rate limiting)",
            "In-memory rate limiting (not suitable for multi-instance deployments without Redis)",
            "No built-in database auto-update mechanism (requires external GeoIP update service)"
          ]
        },
        {
          "title": "Documentation",
          "items": [
            "**README.md** - Quick start guide and overview",
            "**CONFIGURATION.md** - Detailed configuration reference for all environment variables",
            "Inline code documentation and TypeScript interfaces"
          ]
        },
        {
          "title": "License",
          "content": "Bitip is proprietary software. Unauthorized use, distribution, or modification is strictly prohibited. Contact the author for licensing inquiries."
        }
      ]
    }
  ]
}