bitip/content/ReleaseNotes.json

{
  "releases": [
    {
      "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."
        }
      ]
    }
  ]
}