proxy-detection/CODE_ORGANIZATION.md

Proxy Detection API - Code Organization

This document describes the organized file structure of the Proxy Detection API.

File Structure

The application has been organized into separate modules for better maintainability:

Core Files

• index.ts - Entry point for the application
• server.ts - Server setup and initialization
• routes.ts - Route definitions and registration

Module Files

• types.ts - TypeScript type definitions and interfaces
• config.ts - Configuration and environment variables
• middleware.ts - Authentication and other middleware functions
• handlers.ts - Route handler functions
• utils.ts - Utility functions for IP detection and processing

Service Files

• proxyService.ts - IP extraction service (existing)

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       index.ts                              │
│                    (Entry Point)                            │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    server.ts                                │
│              (Server Configuration)                         │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │   config    │ │ middleware  │ │        routes           ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   handlers.ts                               │
│               (Route Handlers)                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │    utils    │ │    types    │ │    proxyService         ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Module Responsibilities

types.ts

• ApiResponse - Main API response interface
• HealthResponse - Health check response interface
• IPChainResult - IP chain result interface
• DetailedDebugResponse - Debug endpoint response interface

config.ts

• Environment variable management
• Server configuration settings
• CORS and trust proxy settings
• Application constants

utils.ts

• getClientIP() - Enhanced IP detection with 30+ header sources
• getFullIPChain() - Extract full proxy chain information
• normalizeHeaders() - Normalize headers to consistent format
• extractGeolocation() - Extract geolocation from headers
• extractProxyInfo() - Extract proxy information from headers

middleware.ts

• authMiddleware() - API key authentication
• Handles both header and query parameter authentication
• Skips authentication for health and debug endpoints

handlers.ts

• healthHandler() - Health check endpoint
• mainHandler() - Main proxy detection endpoint
• randomHandler() - Random cached result endpoint
• detailedDebugHandler() - Detailed debug information endpoint
• In-memory result caching management

routes.ts

• Route registration and organization
• Maps endpoints to their respective handlers
• Maintains authentication bypass configuration

server.ts

• Fastify server instance creation
• CORS configuration
• Middleware registration
• Server startup and error handling

Benefits of This Organization

1. Separation of Concerns - Each file has a specific responsibility
2. Maintainability - Easier to locate and modify specific functionality
3. Testability - Individual modules can be unit tested independently
4. Reusability - Utility functions can be easily reused
5. Type Safety - Centralized type definitions ensure consistency
6. Configuration Management - All settings are centralized and manageable

Development Workflow

1. Adding new endpoints: Add handler to handlers.ts, register route in routes.ts
2. Modifying IP detection: Update functions in utils.ts
3. Changing configuration: Update config.ts
4. Adding new types: Add to types.ts
5. Adding middleware: Add to middleware.ts

Running the Application

The application starts from index.ts which:

1. Creates a server instance
2. Configures middleware and routes
3. Starts the server
4. Handles startup errors

All functionality remains the same as the original monolithic version, but is now organized for better maintainability and scalability.