Vitron-Front/docs/API_CONFIGURATION.md

API Configuration Guide

Overview

This document outlines the robust, environment-aware API configuration system implemented for the Vitron frontend application. The system eliminates hardcoded API endpoints and provides dynamic configuration based on environment variables.

Architecture

🏗️ Core Components

1. Dynamic BASE_PATH (src/api/types/runtime.ts)

   • Auto-generated API types now use environment-aware BASE_PATH
   • Supports both client-side and server-side environments
   • Graceful fallbacks for different deployment scenarios

2. Centralized API Config (app/utils/api-config.ts)

   • Utility functions for all API endpoints (HTTP, WebSocket, Site URLs)
   • Environment detection and fallback logic
   • Type-safe configuration management

3. API Client Factory (app/utils/api-client-factory.ts)

   • Centralized factory for creating configured API clients
   • Consistent authentication header management
   • Single source of truth for API configuration

🌍 Environment Configuration

Development Environment

VITE_API_BASE_URL=https://api.dev.vitrown.com
VITE_API_SOCKET_BASE_URL=wss://api.dev.vitrown.com
VITE_SITE_URL=https://dev.vitrown.com
VITE_DOMAIN_URL=https://dev.vitrown.com

Production Environment

VITE_API_BASE_URL=https://api.prod.vitrown.com
VITE_API_SOCKET_BASE_URL=wss://api.prod.vitrown.com
VITE_SITE_URL=https://vitrown.com
VITE_DOMAIN_URL=https://vitrown.com

🔄 Configuration Resolution Order

The system follows this priority order for configuration resolution:

1. Client-side Remix ENV injection (window.ENV.VITE_*)
2. Vite import.meta.env (build-time injection)
3. Node.js process.env (server-side)
4. Environment-based fallbacks
5. Static fallbacks (development defaults)

📝 Usage Examples

Using API Client Factory (Recommended)

import { createUserManagementApi } from "~/utils/api-client-factory";

// In your hook or component
const userApi = createUserManagementApi(token);
const response = await userApi.userManagementSendOtpPost({
  phoneNumber: "1234567890"
});

Using Centralized Config

import { getApiBaseUrl, getSocketBaseUrl } from "~/utils/api-config";

// For WebSocket connections
const wsUrl = `${getSocketBaseUrl()}/ws/chat/${threadId}/?token=${token}`;

// For manual fetch calls
const response = await fetch(`${getApiBaseUrl()}/api/custom-endpoint`);

Environment Detection

import { isProduction, isDevelopment } from "~/utils/api-config";

if (isProduction()) {
  // Production-specific logic
}

🚀 Benefits

DevOps Advantages

1. Environment Parity: Same codebase works across all environments
2. Configuration as Code: All API endpoints defined in environment variables
3. Zero Hardcoded Values: No more environment-specific builds
4. Deployment Flexibility: Easy to switch between staging/prod domains
5. Container-Ready: Perfect for Docker and Kubernetes deployments

Development Benefits

1. Type Safety: Full TypeScript support with proper fallbacks
2. Centralized Management: Single source of truth for all API configuration
3. Consistent Auth: Automatic bearer token injection
4. Error Resilience: Graceful fallbacks prevent runtime failures

🔧 Migration Guide

Updating Existing Hooks

Before:

const basePath = import.meta.env.VITE_API_BASE_URL;
const config = new Configuration({
  basePath,
  headers: { /* ... */ }
});
const api = new UserManagementApi(config);

After:

import { createUserManagementApi } from "~/utils/api-client-factory";
const api = createUserManagementApi(token);

Updating WebSocket Connections

Before:

const baseSocketPath = import.meta.env.VITE_API_SOCKET_BASE_URL;

After:

import { getSocketBaseUrl } from "~/utils/api-config";
const baseSocketPath = getSocketBaseUrl();

🧪 Testing Configuration

Local Development

# Test development configuration
npm run dev

# Test production configuration locally
NODE_ENV=production npm run build
npm run start

Environment Variables Testing

# Override for testing
VITE_API_BASE_URL=https://api.staging.vitrown.com npm run dev

🔒 Security Considerations

1. No Secrets in Config: Only public endpoints are configured
2. Runtime Token Injection: Authentication tokens added at request time
3. Fallback Safety: Default fallbacks prevent exposure of internal services
4. Type Safety: Prevents configuration errors at compile time

📊 Monitoring & Debugging

Environment Verification

import { getApiConfig } from "~/utils/api-config";

console.log("Current API Configuration:", getApiConfig());

Build-time Verification

Check your build output for correct environment variable injection:

npm run build
# Verify the built files contain correct API endpoints

🚨 Troubleshooting

Common Issues

1. Undefined Environment Variables

   • Ensure .env.production has all required variables
   • Check Vite prefix requirements (VITE_ prefix)

2. Server-Side vs Client-Side

   • Use window.ENV for Remix server-injected variables
   • Use import.meta.env for Vite build-time injection

3. Docker/Container Issues

   • Ensure environment variables are passed to container
   • Use docker-compose.yml environment section

Debug Commands

# Check current environment
npm run generate:types  # Regenerate API types
npm run typecheck      # Verify TypeScript compilation
npm run build         # Test production build

🎯 Future Enhancements

• Runtime configuration refresh (for long-running apps)
• Configuration validation middleware
• Health check endpoints for configuration verification
• Automated environment variable documentation generation