Feature: Interactive Map
Relevant source files
The following files were used as context for generating this wiki page:The Interactive Map feature is a core component of the LLaMa Leaks application, designed to provide a real-time, geographical visualization of publicly exposed Ollama AI servers. Its primary purpose is educational, demonstrating the global scale of unsecured AI infrastructure to raise security awareness among developers. The feature is encapsulated within the LocationInfo component, which fetches data for a random exposed server and displays its location on an interactive map rendered by the Map component.
This feature directly supports the project's mission to "help developers discover their exposed infrastructure before malicious actors do, through real-time monitoring and gentle public awareness." While the LocationInfo component is fully implemented, its integration into a specific page is not present in the analyzed files like Index.tsx or About.tsx.
Sources: frontend/src/components/LocationInfo.tsx, frontend/src/components/Map.tsx, frontend/src/pages/About.tsx:50-53
Architecture and Component Relationship
The feature is built around two main React components: LocationInfo and Map. LocationInfo acts as a container component responsible for data fetching and state management, while Map is a presentational component responsible for rendering the map visualization.
LocationInfo.tsx: The parent component that orchestrates the feature. It fetches data for a random server, manages loading and error states, and passes the necessary geographical data to theMapcomponent.Map.tsx: The child component that receives coordinates and location details as props. It uses the Mapbox GL JS library to render an interactive map, place a marker at the server's location, and handle theme changes (light/dark mode).
Sources: frontend/src/components/LocationInfo.tsx:220-226, frontend/src/components/Map.tsx:11-16
The following diagram illustrates the relationship between these components.
This diagram shows that the LocationInfo component controls the Map component by passing down location data as props.
Sources: frontend/src/components/LocationInfo.tsx:220-226
Data Flow and Management
The data for the map is sourced from a static JSON file and fetched dynamically on the client side. The LocationInfo component manages the entire data lifecycle.
Data Fetching
The fetchRandomServer function in LocationInfo.tsx is responsible for retrieving the server data.
- It initiates a fetch request to
/data/live_servers.json. - Upon receiving the response, it parses the JSON, which is an object where keys are server identifiers and values are server data objects.
- It converts this object into an array of server data objects.
- A random server is selected from the array.
- The component's state (
serverData) is updated with the randomly selected server's information, triggering a re-render to display the new data and update the map.
The component also handles loading and error states throughout this process. A "Random Server" button allows the user to trigger this flow again to view a different server.
Sources: frontend/src/components/LocationInfo.tsx:38-65, frontend/src/components/LocationInfo.tsx:241-264
The sequence diagram below shows the data fetching process.
Data Structure
The data for each server is expected to conform to the ServerData interface defined within LocationInfo.tsx.
| Field | Type | Description |
|---|---|---|
ip | string | The IP address of the server. |
port | number | The port number the Ollama service is running on. |
version | string | The version of the Ollama instance. |
city | string | The city where the server is located. |
country | string | The two-letter country code (e.g., 'US'). |
country_name | string | The full name of the country. |
region | string | The region or state. |
latitude | string | The geographical latitude. |
longitude | string | The geographical longitude. |
local | ServerModel[] | An array of AI models available locally on the server. |
running | ServerModel[] | An array of AI models currently running in memory. |
first_seen_online | string | An ISO 8601 timestamp of when the server was first detected. |
age | string | A human-readable string representing how long the server has been online. |
status | string | The current status of the server (e.g., 'live'). |
Sources: frontend/src/components/LocationInfo.tsx:13-28
Map Component (Map.tsx)
This component is a specialized wrapper around the Mapbox GL JS library, responsible for all map rendering logic.
Configuration and Initialization
The map requires a Mapbox access token, which must be provided via an environment variable.
| Environment Variable | Description |
|---|---|
VITE_MAPBOX_TOKEN | The public access token for Mapbox services. |
If this token is not provided, the component will display a specific error message.
Sources: frontend/src/components/Map.tsx:63-65
The initialization process, handled by the initializeMap function, follows a clear sequence to ensure the map loads correctly.
This flowchart outlines the robust initialization logic, including theme detection, marker creation, and error handling for both token configuration and map loading issues.
Sources: frontend/src/components/Map.tsx:48-175
Properties
The Map component accepts the following props to display a location:
| Prop | Type | Description |
|---|---|---|
latitude | string | The latitude for the map center and marker. |
longitude | string | The longitude for the map center and marker. |
city | string | The city name, used in the marker popup. |
country | string | The country name, used in the marker popup. |
Sources: frontend/src/components/Map.tsx:11-16
Theming and Style
The map's appearance is dynamically adjusted based on the application's theme (light or dark), which is managed by ThemeProvider.
- Dark Mode:
mapbox://styles/mapbox/dark-v11 - Light Mode:
mapbox://styles/mapbox/light-v11
The component listens for theme changes using the useTheme hook and updates the map style accordingly. When the style changes, it also re-adds the location marker with a theme-appropriate color to ensure visibility.
Sources: frontend/src/components/Map.tsx:21-22, frontend/src/components/Map.tsx:81-83, frontend/src/components/Map.tsx:189-218
Error Handling
The Map component includes comprehensive error handling for a better user experience.
- Loading State: An overlay with a spinner is shown while the map is initializing.
- Error State: If an error occurs (e.g., invalid token, network issue, loading timeout), an overlay is displayed with a descriptive error message. Specific messages are provided for common issues like 401 (Unauthorized), 429 (Rate Limit Exceeded), and 403 (Forbidden).
Sources: frontend/src/components/Map.tsx:114-127, frontend/src/components/Map.tsx:275-295
Dependencies
The feature relies on several key third-party libraries defined in package.json.
| Package | Version | Usage |
|---|---|---|
mapbox-gl | ^3.13.0 | The core library for rendering interactive maps. |
react | ^18.3.1 | The UI framework. |
lucide-react | ^0.462.0 | Provides icons used in the UI (e.g., MapPin, Loader2). |
next-themes | ^0.3.0 | Used via ThemeProvider to manage light/dark mode for map styling. |
Sources: frontend/package.json:48, 49, 51, 52, frontend/src/components/Map.tsx:2, 5, frontend/src/App.tsx:21
Conclusion
The Interactive Map is a well-architected feature that effectively combines data fetching, state management, and a powerful third-party mapping library to visualize security vulnerabilities. The clear separation of concerns between the LocationInfo and Map components makes the system maintainable and easy to understand. By providing real-time, visual evidence of exposed servers, this feature serves as a compelling educational tool that directly advances the project's core mission of improving internet security.
Sources: frontend/src/components/LocationInfo.tsx, frontend/src/components/Map.tsx, frontend/src/pages/About.tsx:47-53