This work corresponds to an applied study with a quantitative approach, oriented toward the development and validation of an automated agricultural soil interpretation tool. The TERRAGEM mobile application was designed to interpret soil analyses using artificial intelligence and generate personalized management recommendations according to crop type. System verification was carried out through functional testing with 29 real soil analysis reports, confirming that the application correctly processes the entered data and generates interpretations through the Gemini API.

The dataset comprises 29 soil characterization analyses corresponding to crops from the province of Cañete (grape, avocado, corn, and sweet potato), obtained from agricultural laboratory reports provided by collaborators of the Universidad Nacional de Cañete for academic purposes. These reports were structured in digital format and used exclusively as functional test cases for the system, in order to verify that the application correctly processes the entered physicochemical parameters and generates coherent interpretations through the Gemini API. Each analysis includes relevant physicochemical variables such as pH, electrical conductivity, organic matter, nitrogen, phosphorus, potassium, calcium, and magnesium. Agronomic experts from the Faculty of Agronomy of the Universidad Nacional de Cañete reviewed the AI-generated interpretations for the test cases, confirming that the recommendations were consistent with the crop type and the entered values.

The reference value ranges by parameter and crop type, used as the basis for the system’s interpretations, are presented in Table 1 (grape), Table 2 (avocado), Table 3 (corn), and Table 4 (sweet potato):

Technologies and libraries

The TERRAGEM mobile application was developed in the Dart language using the Flutter framework (v3.24.3/Dart ≥3.0.0), enabling the construction of a modern, intuitive, and cross-platform interface oriented toward the automated interpretation of soil analyses. Development and testing were carried out on a Lenovo Ideapad Slim 3i laptop (Intel Core i5-12450H, 16 GB RAM, 512 GB SSD), using the Android x64 Medium Phone emulator (API 36.1) to validate functionality in real mobile environments.

The system connects to a cloud database via Supabase, a platform used for user management, storage of soil analyses, and interpretation history. Automated interpretation of results is performed through the Gemini API (Google AI), which processes the analysis data and generates technical descriptions with agronomic recommendations. Integration with the OpenWeatherMap API provides real-time climate data, enriching the interpretation of soil conditions.

The main project dependencies, with their versions recorded in the repository’s pubspec.yaml file, are as follows: supabase_flutter ^2.10.1, google_generative_ai ^0.4.3, http ^1.5.0, geolocator ^12.0.0, google_maps_flutter ^2.6.0, pdf ^3.10.6, path_provider ^2.1.3, open_filex ^4.3.2, permission_handler ^12.0.1, flutter_dotenv ^6.0.0, google_fonts ^6.1.0, cupertino_icons ^1.0.8. These libraries enable communication with external APIs, geographic location services, PDF report generation, file opening, Android permission management, typographic customization, and environment variable loading.

Development methodology (RAD)

The agile Rapid Application Development (RAD) methodology was used, enabling rapid and effective software implementation through iterative, user-centered cycles. The process was structured in five phases, whose lifecycle is illustrated in Figure 1. ▪

Phase 1: Requirements gathering

In this phase, the functional and non-functional requirements tables were developed, identifying the needs of the end user: primarily farmers and soil specialists. The essential system modules were defined (user registration, soil analysis upload, AI interpretation, and results visualization), and the acceptance criteria and technical specifications were established to ensure system scalability and reliability. The identified functional requirements are detailed in Table 5, while the non-functional requirements are presented in Table 6.

Graphical interface and processing workflow

The TERRAGEM application features an interactive and intuitive interface that allows the farmer to manually register soil analysis results by entering the physicochemical parameters obtained from the laboratory. Once the data is entered, the system executes an automatic validation process that verifies the coherence of the values and the completeness of the information.

The validated data is processed by the Gemini AI API, which generates an automated interpretation of the soil status, identifying possible deficiencies and providing management recommendations. Additionally, the application integrates the OpenWeatherMap API to display current weather conditions and the Google Maps API to visualize nearby agricultural stores.

The results are presented in a simple visual interface that displays the entered quantitative information alongside the AI-generated interpretation, facilitating understanding of the soil status diagnosis. From this same view, the user can generate a PDF report and access their previous analysis history. Figure 2 schematically illustrates the application’s processing workflow, from user interaction to the return of the AI-generated interpretation.

The TERRAGEM mobile application is designed to run on Android devices with an internet connection, as its operation depends on external cloud services (Supabase, Gemini AI, and OpenWeatherMap). The minimum requirements for the end user and the local development environment are detailed below.

Minimum mobile device requirements (end user) o

Operating system: Android 10 (API 29) or higher.

Local development environment requirements (developer) o

Operating system: Windows 10 or higher, macOS 13 or higher, or Ubuntu 22.04.

User workflow (end user)

Once the application is installed, the user registers or logs in, then accesses the main screen where the current weather conditions of their location are automatically displayed. The user then selects the crop type and registers their plot data. In the analysis module, the physicochemical soil values obtained from the laboratory are manually entered (pH, nitrogen, phosphorus, potassium, organic matter, electrical conductivity, and calcium). The system sends this data to the Gemini API, which generates an automated interpretation with agronomic recommendations. The user can view the result on screen, generate a PDF report, and consult their previous analysis history.

Execution in development environment

To run the application in development mode, a terminal must be opened in the project directory and the command flutter run executed. Either the Android x64 emulator (API 29 or higher) or a physical device connected via USB with debugging enabled can be used. The environment variables required for the APIs must be previously configured in the project’s.env file, following the structure defined in the repository.

The TERRAGEM project used data from real soil analyses supplied by agricultural laboratories in the province of Cañete, ensuring the confidentiality and anonymity of the sources at all times. The data were used exclusively for academic and research purposes, respecting the principles of transparency, integrity, and responsible use of information. The system was designed as a technical support tool, not as a substitute for the professional judgment of the specialist. The AI-generated interpretations were validated by faculty members and agronomic engineers from the Faculty of Agronomy of UNDC. Ethical approval was not required for this study, as the research involved only anonymized physicochemical data obtained from agricultural soil analysis reports and did not involve human participants, biological samples, or personal data. The soil data were provided voluntarily by collaborators of the Universidad Nacional de Cañete for academic purposes. No human participants were enrolled in this study; therefore, informed consent was not applicable.

After authenticating in the application ( Figure 3), the user accesses the main screen, where the system automatically displays the current weather conditions of their location via the OpenWeatherMap API ( Figure 4). The farmer then selects the crop type to be analyzed ( Figure 5) and registers the plot size in hectares or square meters ( Figure 6). Finally, the predominant soil type in their plot is selected — sandy loam, clay, or silty — ( Figure 7), configuring the basic parameters of the analysis environment.

The user accesses the analysis module and manually registers the soil physicochemical values — pH, phosphorus, potassium, nitrogen, organic matter, cation exchange capacity, and electrical conductivity — as shown in Figure 8. Once entered, the system sends them to the Gemini API, which generates a detailed response including the evaluation of the current soil status, identification of nutritional deficiencies, and technical recommendations tailored to the selected crop. The interpretation is presented in a visual and interactive format with explanatory text and visual indicators of critical values, as shown in Figure 9.

The user can generate a PDF report containing the complete interpretation performed by Gemini, the analysis data, the date, and the analyzed crop ( Figure 10). These reports are stored in the user’s history, accessible from the main menu ( Figure 11). The system also offers a geolocation feature that allows nearby fertilizer and agricultural product stores to be visualized ( Figure 12), providing practical options for applying the report’s recommendations.

Together, the described use cases represent the integral workflow of the TERRAGEM system, from user authentication and agricultural environment configuration, through to automatic interpretation and final report generation, demonstrating the efficiency and practical applicability of the system as an intelligent support tool for the sustainable management of agricultural soils.