Federated Geocoding Service - Frontend

This is the frontend application for the Federated Geocoding Service. It's a React-based web application that leverages browser geolocation and IP-based services to determine the user's location and provide related intelligence.

Features

• Automatic Location Detection: Automatically attempts to detect the user's location using high-accuracy browser geolocation.
• IP-Based Location Fallback: If browser geolocation fails or is denied, it falls back to using IP address-based location services.
• IP Intelligence: Displays detailed intelligence information associated with the user's IP address.
• Location Caching: Stores fetched location data and IP intelligence locally to improve performance and reduce redundant API calls.
• Provider Information: Clearly indicates the source of the location data (e.g., Browser Geolocation API, IP-based service).
• Status Indicators: Provides visual feedback on the loading and error states of the services.
• Responsive Design: Built with modern web technologies for a good user experience across devices.

Technologies Used

• React: A JavaScript library for building user interfaces.
• Vite: A fast, opinionated build tool for modern web development.
• TypeScript: For static typing and improved developer experience.
• React Router (Implicit): While not explicitly seen in App.tsx, typically used for navigation in React apps. (Note: This is an assumption based on common React project structure. If routing is a key feature, further investigation might be needed.)
• Leaflet: A JavaScript library for interactive maps (indicated by leaflet dependency).
• Tailwind CSS: A utility-first CSS framework for rapid UI development (inferred from class names like bg-gray-50, dark:bg-gray-900, font-sans, p-4, rounded-lg, shadow-md, etc.).
• Lucide React: A library of SVG icons.
• Node-fetch: Used for making API requests from the frontend.

Setup and Installation

1. Clone the repository:

   git clone <repository-url>
   cd federated-geocoding-service

2. Install dependencies:

   npm install

3. Environment Variables: Create a .env file in the root directory (alongside package.json) and configure the necessary environment variables. Example .env file:

   VITE_API_BASE_URL=http://localhost:3001
   # Add any other frontend-specific environment variables here

   Note: The backend is expected to be running on http://localhost:3001 by default.

Running the Application

1. Start the development server:

   npm run dev

   This command will start the Vite development server, typically accessible at http://localhost:5173 (or another port if 5173 is in use).

2. Build for production:

   npm run build

   This command creates a production-ready build in the dist/ directory.

3. Preview the production build:

   npm run preview

   This command serves the production build locally for testing.

Running with Docker

To run the application using Docker, you can use the provided docker-compose.yml file. This will build and run both the frontend and backend services.

1. Build and start the containers:

   docker-compose up --build

   This command will build the Docker images if they don't exist and then start the containers. The frontend will be accessible at http://localhost:80 and the backend at http://localhost:3001.

2. Stop the containers: To stop the running containers, press Ctrl+C in the terminal where docker-compose up is running. To remove the containers, networks, and volumes, use:

   docker-compose down

Contributing

Contributions are welcome! Please refer to the project's contribution guidelines.

Deploying to Render Cloud

Render is a cloud platform that simplifies deploying web applications. Here's how you can deploy this project:

Backend Deployment

1. Create a new Node.js service on Render:
   • Go to your Render dashboard and click "New +" -> "Web Service".
   • Connect your GitHub repository.
   • App Settings:
     • Name: Give your service a name (e.g., geocoding-backend).
     • Region: Choose a region close to your users.
     • Branch: Select the branch you want to deploy (e.g., main).
     • Root Directory: Set this to backend/ as your Dockerfile is located there.
     • Build Command: npm install && npm run build
     • Start Command: npm run serve
   • Environment Variables:
     • Add any necessary environment variables (e.g., PORT=3001, API keys for external services). You can use Render's secret management for sensitive information.
   • Click "Create Web Service". Render will build and deploy your backend.

Frontend Deployment

1. Create a new Static Site service on Render:
   • Go to your Render dashboard and click "New +" -> "Static Site".
   • Connect your GitHub repository.
   • App Settings:
     • Name: Give your service a name (e.g., geocoding-frontend).
     • Region: Choose a region close to your users.
     • Branch: Select the branch you want to deploy (e.g., main).
     • Build Command: npm install && npm run build
     • Publish Directory: dist/
   • Environment Variables:
     • You will need to set the VITE_API_BASE_URL environment variable for the frontend to communicate with your deployed backend. Set this to the URL of your deployed backend service (e.g., https://geocoding-backend.onrender.com).
   • Click "Create Static Site". Render will build and deploy your frontend.

Important Notes:

• Ensure your backend service is deployed and running before deploying the frontend, so you can correctly set the VITE_API_BASE_URL.
• Render's free tier has limitations on build times and idle periods. For production, consider upgrading.

How Other Apps May Query the Backend

Other applications can query the backend API by making HTTP requests to the exposed endpoints. The base URL for the backend API will depend on where it is deployed.

Example API Endpoints:

• Get IP Location: GET /api/ip-location
• Get IP Intelligence: GET /api/ip-intelligence?ip=<ip_address>
• Get Location by Coordinates: POST /api/location with body { "lat": <latitude>, "lon": <longitude> }

For detailed information on request and response formats, please refer to the Backend API Endpoints section in the backend's README.

Overall Process

1. A user accesses the frontend application via their web browser.
2. The frontend attempts to get the user's location using the browser's Geolocation API.
3. If successful, the frontend displays the location details and potentially uses it to query the backend for more information (e.g., IP intelligence for the user's IP).
4. If browser geolocation fails or is denied, the frontend requests the user's IP address and location from the backend (GET /api/ip-location).
5. The backend receives the request, determines the user's IP address, and uses IP-based services to find location and intelligence data.
6. The backend returns this data to the frontend.
7. The frontend displays the obtained location and intelligence information, potentially including a map visualization.
8. Client-side fingerprint data may also be sent to the backend for logging.