Frontend: Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The frontend of LLaMa Leaks is a modern web application built with React and TypeScript. It is designed to be a fast, responsive, and visually appealing single-page application (SPA) that presents data about exposed Ollama AI servers. The architecture leverages the Vite build tool for a rapid development experience and optimized production builds.
The core of the application is its component-based structure, facilitated by React. Reusable UI elements are built using the Shadcn/UI library, which provides unstyled components that are then customized using Tailwind CSS. This approach allows for a highly consistent and maintainable design system, with theming capabilities for both light and dark modes defined through CSS variables.
Project Setup & Tooling
The project is configured as a standard Node.js project, managed via package.json. It uses Vite as its development server and build tool, which provides features like Hot Module Replacement (HMR) for a fast development cycle.
Sources: frontend/package.json, frontend/vite.config.ts
Build & Development Scripts
The following scripts are defined for managing the application lifecycle:
| Script | Description |
|---|---|
dev | Starts the Vite development server on 127.0.0.1:8080. |
build | Compiles the TypeScript and React code into a production-ready dist directory. |
lint | Runs ESLint to analyze the code for potential errors and style issues. |
preview | Serves the production build locally to preview the final application. |
Sources: frontend/package.json:7-12, frontend/vite.config.ts:8-11
Build Process
The Vite build process transforms the source files (.tsx, .css) into optimized static assets (HTML, JS, CSS) suitable for deployment.
This diagram illustrates the high-level build flow.
Core Libraries & Dependencies
The application relies on a curated set of libraries to handle UI, routing, data fetching, and other concerns.
| Library | Category | Description |
|---|---|---|
react | UI Framework | The core library for building the user interface with components. |
react-router-dom | Routing | Manages client-side routing and navigation between pages. |
@tanstack/react-query | Data Fetching | Handles server-state, including fetching, caching, and updating data. |
tailwindcss | Styling | A utility-first CSS framework for rapid UI development. |
shadcn-ui / @radix-ui/* | Component Library | Provides a set of accessible, unstyled UI components. |
lucide-react | Icons | A library of simply beautiful and consistent icons. |
vite | Build Tool | A modern frontend tool for development and building. |
typescript | Language | A typed superset of JavaScript that compiles to plain JavaScript. |
Sources: frontend/package.json:14-72
Styling & UI
The visual layer is built upon Tailwind CSS and the Shadcn/UI component library. This combination provides a powerful and flexible system for creating a consistent design.
Theming
The application supports both light and dark themes. Theming is implemented using CSS custom properties (variables) defined in src/index.css. A .dark class on a parent element (typically <body>) switches the active theme.
/* frontend/src/index.css:8-35 */
@layer base {
:root {
--background: 210 50% 96%;
--foreground: 210 20% 12%;
--primary: 210 100% 47%;
/* ... other light theme variables */
}
.dark {
--background: 210 13% 9%;
--foreground: 210 40% 98%;
--primary: 210 100% 56%;
/* ... other dark theme variables */
}
}
Sources: frontend/src/index.css:8-74
Component Library (Shadcn/UI)
Shadcn/UI is used for foundational UI components like Button, Card, and Badge. Its configuration is defined in components.json, which specifies path aliases and the location of the Tailwind CSS configuration and base CSS file. This setup allows developers to easily add new components from the Shadcn/UI library.
| Configuration Key | Value | Description |
|---|---|---|
style | default | The default style for components. |
tailwind.config | tailwind.config.ts | Path to the Tailwind CSS configuration file. |
tailwind.css | src/index.css | Path to the main CSS file where Tailwind directives are. |
tailwind.baseColor | slate | The base color palette for generating shades. |
aliases.components | @/components | Path alias for component files. |
aliases.utils | @/lib/utils | Path alias for utility functions. |
Sources: frontend/components.json
Application Structure & Routing
The application is structured into pages and reusable components. The entry point is index.html, which loads the main React script.
Sources: frontend/index.html:26, frontend/src/pages/Index.tsx
Component Hierarchy
The main page (Index.tsx) assembles several high-level components to build the user interface.
This diagram shows the component composition for the main page.
Sources: frontend/src/pages/Index.tsx:5-11
Routing
Client-side routing is handled by react-router-dom. The Index.tsx page demonstrates how useLocation hook is used to read the URL's hash (#) and scroll to the corresponding element on the page, enabling smooth navigation to sections like #solutions.
Sources: frontend/src/pages/Index.tsx:20-29, frontend/package.json:62
Data Fetching & State Management
The application fetches dynamic data to display information about exposed servers. The LocationInfo component is a key example of this pattern.
Data Fetching Flow
The LocationInfo component fetches a list of servers from a static JSON file, selects one at random, and displays its details. It manages its own state for loading, error, and data using React hooks.
This sequence diagram illustrates the data fetching process within the LocationInfo component.
Data Structure
The data for each server is expected to follow the ServerData interface.
| Field | Type | Description |
|---|---|---|
ip | string | The masked IP address of the server. |
port | number | The port number the service is running on. |
version | string | The Ollama version string. |
city | string | The city where the server is located. |
country | string | The two-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 models available locally on the server. |
running | ServerModel[] | An array of 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 of how long the server has been online. |
status | string | The current status, e.g., "live". |
Sources: frontend/src/components/LocationInfo.tsx:14-28
Conclusion
The frontend architecture of LLaMa Leaks is robust, modern, and maintainable. By using Vite, React, and TypeScript, it establishes a strong foundation for development. The strategic use of Tailwind CSS and Shadcn/UI ensures a consistent and high-quality user interface, while react-router-dom and @tanstack/react-query provide reliable solutions for navigation and data management. The clear separation of concerns into pages and components makes the codebase easy to understand and extend.