System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
LLaMa Leaks is a passive AI security awareness project designed to highlight publicly exposed Ollama servers. The system is architected as a modern, client-side rendered web application. It does not perform any active scanning or hacking; instead, it displays pre-collated data about servers that are already publicly accessible. The primary goal is educational: to demonstrate the risks of unsecured AI infrastructure and promote better security practices.
The architecture is intentionally simple, consisting of a static frontend application that consumes a JSON data file. This approach ensures the project itself is secure, scalable, and easy to maintain, focusing entirely on presenting the security information in an effective and slightly sarcastic manner.
Sources: README.md, frontend/src/pages/About.tsx:43-51
High-Level Architecture
The system follows a simple client-server model where the "server" is a static file host. The user's browser downloads the React application, which then fetches data from a static JSON file to populate the dynamic parts of the UI, such as the live server evidence section.
This diagram illustrates the basic data flow from the user to the application's data source.
Frontend Technology Stack
The frontend is a modern web application built using Vite, React, and TypeScript. It leverages several key libraries for UI, state management, and functionality.
| Library/Tool | Purpose | Source -
| react | Core UI library for building components. | frontend/package.json:52 -
| vite | Build tool providing a fast development experience. | frontend/package.json:4, 86 -
| tailwindcss | A utility-first CSS framework for rapid UI development. | frontend/package.json:84, frontend/src/index.css:2 -
| shadcn/ui & @radix-ui | A collection of re-usable UI components, built on Radix UI primitives. Used for Cards, Buttons, etc. | frontend/package.json:11-37, frontend/src/pages/About.tsx:4 -
| lucide-react | Provides a library of SVG icons used throughout the application. | frontend/package.json:50, frontend/src/pages/About.tsx:7 -
| mapbox-gl | Used to render the interactive map in the LocationInfo component. | frontend/package.json:51, frontend/src/components/LocationInfo.tsx:4 -
Sources: frontend/package.json
Data Handling
The application's core dynamic feature is displaying data about a randomly selected exposed server. This process is self-contained within the LocationInfo component.
Data Fetching Flow
The LocationInfo component fetches server data from a static JSON file when it mounts and allows the user to refresh this data.
This sequence diagram shows the process:
Data Structure
The application uses a well-defined ServerData interface to structure the information about each exposed server. This ensures type safety and predictable data handling within the components.
The structure of the server data is defined as follows:
Below is a detailed breakdown of the ServerData fields:
| Field | Type | Description |
|---|---|---|
ip | string | The masked 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 country name (e.g., 'United States'). |
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 | The ISO timestamp of when the server was first seen. |
age | string | A human-readable string of how long it has been seen. |
status | string | The current status, e.g., 'live'. |
Sources: frontend/src/components/LocationInfo.tsx:13-25
UI Components and Styling
The user interface is built from a series of reusable React components, styled with TailwindCSS. The project follows a clear component-based architecture, separating pages, shared components, and UI primitives.
Component Structure
The application is composed of several key components that provide its features and information.
This diagram shows a simplified view of how pages are constructed from shared and feature-specific components.
Sources: frontend/src/pages/About.tsx:1-7, frontend/src/components/LocationInfo.tsx:4, frontend/src/components/Features.tsx:5-12
Styling and Theme
The project uses TailwindCSS for utility-first styling. A design system with light and dark modes is defined in index.css using CSS variables. This allows for a consistent look and feel across the entire application and easy theming capabilities.
Key design tokens defined include:
--background/--foreground--primary/--primary-foreground--destructive--card--border--radius
Sources: frontend/src/index.css:7-80
Conclusion
The LLaMa Leaks system architecture is a lean and effective implementation of a static-site generator pattern using React and Vite. By decoupling the data (live_servers.json) from the presentation layer, the application remains simple, secure, and focused on its educational mission. The component-based structure and modern frontend stack allow for a rich user experience while clearly communicating the security risks of exposed AI servers.
Sources: README.md, frontend/src/components/LocationInfo.tsx