Frontend: State Management & Data Fetching
Relevant source files
The following files were used as context for generating this wiki page:The frontend application employs a combination of component-level state and custom React hooks to manage application state and fetch data about exposed Ollama servers. For simple, single-server displays, data fetching logic is encapsulated directly within components. For more complex views like the dashboard, a structured approach using custom hooks (useModelData, useModelFilters) is used to separate concerns and manage a larger, interactive dataset.
The core data source for the application is a static JSON file, /data/live_servers.json, which is fetched on the client-side. The application uses @tanstack/react-query for data fetching, although some components also use the native fetch API directly. State management for UI, such as loading, error, and refresh states, is handled explicitly within components and hooks.
Data Fetching Patterns
Two primary data fetching patterns are observed in the codebase: direct fetching within components for displaying a single random server, and a custom hook-based approach for the comprehensive model execution dashboard.
Single Random Server Fetching
Components like Hero and LocationInfo are responsible for fetching and displaying data for a single, randomly selected server from the main dataset. This logic is self-contained within each component.
The data fetching flow is as follows:
This diagram illustrates the sequence of events when a component fetches the list of servers and selects one at random to display.
Sources: frontend/src/components/Hero.tsx:40-61, frontend/src/components/LocationInfo.tsx:32-53
State Management
Each component manages its own state using useState.
| State Variable | Type | Description | Source Files |
|---|---|---|---|
serverData | ServerData | null | Stores the data of the randomly selected server. | Hero.tsx:34, LocationInfo.tsx:26 |
loading | boolean | Indicates if the initial data fetch is in progress. | Hero.tsx:35, LocationInfo.tsx:27 |
refreshing | boolean | Indicates if a data refresh (new random server) is in progress. | Hero.tsx:36, LocationInfo.tsx:28 |
error | string | null | Stores any error message from the fetch operation. | Hero.tsx:37, LocationInfo.tsx:29 |
Sources: frontend/src/components/Hero.tsx:34-37, frontend/src/components/LocationInfo.tsx:26-29
Data Structures
The fetched data is expected to conform to the ServerData and ServerModel interfaces.
ServerModel Interface
| Field | Type | Description |
|---|---|---|
name | string | The name of the AI model. |
model | string | The model identifier. |
size | number | The size of the model in bytes. |
ServerData Interface
| Field | Type | Description |
|---|---|---|
ip | string | Masked IP address of the server. |
port | number | The port number. |
version | string | The Ollama version. |
city | string | The city where the server is located. |
country | string | The 2-letter country code. |
country_name | string | The full country name. |
region | string | The region or state. |
latitude | string | The geographical latitude. |
longitude | string | The geographical longitude. |
local | ServerModel[] | An array of locally available models. |
running | ServerModel[] | An array of currently running models. |
first_seen_online | string | ISO timestamp of when the server was first seen. |
last_observed | string | ISO timestamp of when the server was last observed (in Hero.tsx). |
age | string | A human-readable string of how long the server has been online. |
status | string | The current status (e.g., 'live'). |
Sources: frontend/src/components/Hero.tsx:10-28, frontend/src/components/LocationInfo.tsx:8-24
Dashboard State & Data Flow
The ModelExecutionDashboard provides a more complex view of all models across all servers. It uses a set of custom hooks to manage data fetching, filtering, and sorting, which promotes better separation of concerns.
Sources: frontend/src/components/ModelExecutionDashboard.tsx
Component Architecture
The dashboard is composed of a main container component that orchestrates several child components, passing down state and callbacks.
This diagram shows the component and hook hierarchy for the Model Execution Dashboard.
Sources: frontend/src/components/ModelExecutionDashboard.tsx:11-33
Custom Hooks
useModelData
This hook is responsible for fetching and processing the server data for the entire dashboard. Although the source code is not provided, its public interface can be inferred from its usage in ModelExecutionDashboard.tsx.
Return Value
| Key | Description |
|---|---|
serverData | The raw array of all server data. |
loading | Boolean flag for the initial data load. |
error | Error object if the fetch fails. |
refreshing | Boolean flag for subsequent data refreshes. |
lastUpdated | Timestamp of the last successful fetch. |
modelExecutions | Processed data, likely an array of all models from all servers. |
uniqueServers | A list of unique server identifiers for filtering. |
fetchServerData | A function to trigger a data fetch or refresh. |
Sources: frontend/src/components/ModelExecutionDashboard.tsx:12-20
useModelFilters
This hook encapsulates all the logic for client-side filtering, searching, and sorting of the modelExecutions data provided by useModelData.
State Management
| State Variable | Setter | Description |
|---|---|---|
searchTerm | setSearchTerm | The string used to filter models by name. |
serverFilter | setServerFilter | The selected server to filter models by. |
statusFilter | setStatusFilter | The selected status to filter by. |
sortBy | setSortBy | The key to sort the models by. |
sortDirection | setSortDirection | The direction of the sort ('asc' or 'desc'). |
currentPage | setCurrentPage | The current page number for pagination. |
Return Value
| Key | Description |
|---|---|
filteredAndSortedModels | The final array of models after all filters and sorting have been applied. |
Sources: frontend/src/components/ModelExecutionDashboard.tsx:22-33
Data Flow for Filtering and Display
The data flows from the fetching hook, through the filtering hook, and is finally paginated and rendered by the UI components.
This flowchart shows how model data is fetched, processed, filtered, and finally rendered in the dashboard.
Sources: frontend/src/components/ModelExecutionDashboard.tsx:35-40
Key Dependencies
The package.json file lists several key libraries that support the state management and data fetching architecture.
| Dependency | Version | Usage |
|---|---|---|
react | ^18.3.1 | The core library for building the UI. |
react-router-dom | ^6.26.2 | Handles client-side routing. |
@tanstack/react-query | ^5.56.2 | Used for fetching, caching, and managing server state. |
zod | ^3.23.8 | Likely used for data validation, although not explicitly shown in the provided component files. |
Sources: frontend/package.json:14, 30, 48, 56
Conclusion
The frontend state management and data fetching strategy is pragmatic and well-suited to the application's needs. It uses simple, component-level state for straightforward views like the Hero section, preventing unnecessary complexity. For the feature-rich ModelExecutionDashboard, it adopts a more robust pattern with custom hooks that cleanly separate data fetching (useModelData) from UI state logic like filtering and sorting (useModelFilters). This architecture keeps components clean and focused on rendering, while the hooks handle the complex state interactions, resulting in a maintainable and scalable system for displaying server data.