reogranized app and added more headers

CODE_ORGANIZATION.md

@@ -0,0 +1,121 @@
+# 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.