API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The VineSight application utilizes a server-side API built with Next.js App Router Route Handlers. These endpoints serve as the backend for the frontend application, handling data persistence with a Supabase PostgreSQL database and integrating with external AI services like Google's Gemini. The API is responsible for CRUD operations on core entities like Farms and Irrigation records, as well as providing AI-driven insights for features such as the chat assistant and growth analysis.
All API routes are defined within the src/app/api/ directory. They handle incoming NextRequest objects and return Response objects, typically with JSON payloads. This architecture provides a clear separation between the client-side UI and server-side business logic, ensuring secure and efficient data management.
General API Flow
The following diagram illustrates the typical sequence of an API request within the VineSight application, from the client to the server and back.
Health & Utility Endpoints
/api/health
This is a simple health check endpoint used to verify that the API server is running and responsive. It returns a static JSON response indicating the service status.
| Method | Description | Response Body |
|---|---|---|
GET | Checks the API service status. | { "status": "healthy" } |
Sources: src/app/api/health/route.ts:1-7
Data Management Endpoints
These endpoints manage the core data entities of the application, such as farms and irrigation records. They directly interact with the Supabase database.
/api/farms
This endpoint handles CRUD operations for farm entities.
| Method | Description | Request Body | Success Response |
|---|---|---|---|
GET | Retrieves a list of all farms for the user. | N/A | 200 OK with an array of Farm objects. |
POST | Creates a new farm record in the database. | A Farm object (without id). | 201 Created with the newly created Farm object. |
The Farm data structure is defined in the application's type definitions.
Sources: src/app/api/farms/route.ts, context/TYPES_AND_INTERFACES.md:5-24
/api/irrigation
This endpoint manages irrigation records associated with a specific farm.
| Method | Description | Request Body | Success Response |
|---|---|---|---|
GET | Retrieves all irrigation records for a farm. | Query param: farmId | 200 OK with an array of irrigation records. |
POST | Creates a new irrigation record for a farm. | An irrigation record object. | 201 Created with the newly created irrigation record. |
Sources: src/app/api/irrigation/route.ts
AI-Powered Endpoints
These endpoints leverage external AI models to provide intelligent features, such as conversational assistance and agricultural analysis.
/api/ai/chat
This endpoint powers the AI assistant, providing conversational responses to user queries about farming. It uses the generateText function from the ai library to interact with a large language model.
The request flow is as follows:
- Receives a POST request with the user's message history.
- Constructs a system prompt to frame the AI as a "VineSight Farming Assistant".
- Sends the prompt and message history to the AI model.
- Streams the AI's response back to the client.
Sources: src/app/api/ai/chat/route.ts:1-29
/api/ai/growth-analysis
This endpoint analyzes the growth stage of grapevines based on farm data, recent activities, and weather patterns. It uses the google/gemini-2.0-flash-lite model.
The following diagram shows the logic flow for a growth analysis request.
Request & Response Structure
The endpoint expects a JSON body with farm, activity, and weather data and returns a structured GrowthStageAnalysis object.
Request Body:
| Field | Type | Description |
|---|---|---|
farmData | Object | Details about the farm, including region and planting date. |
activities | Array | A list of recent farming activities. |
weather | Object | Recent weather patterns. |
Response Body (GrowthStageAnalysis):
| Field | Type | Description |
|---|---|---|
stage | string | The identified growth stage (e.g., flowering). |
confidence | number | The AI's confidence in the analysis (0.0-1.0). |
recommendations | string[] | Actionable advice for the current stage. |
timeRelevant | boolean | Indicates if the analysis is time-sensitive. |
nextStageDate | string | The estimated date of the next growth stage. |
description | string | A brief explanation of the analysis. |
A fallback mechanism is in place to provide a generic analysis if the AI service fails, ensuring the application remains resilient.
Sources: src/app/api/ai/growth-analysis/route.ts:4-11, src/app/api/ai/growth-analysis/route.ts:68-98
Data Export
While not a direct API endpoint in the same vein as the others, the ExportService class defines the logic for generating and downloading farm data reports in CSV and PDF formats. This service is likely consumed by a dedicated export page/route.
The exportData method orchestrates the process:
- Gathers all relevant data from Supabase based on the provided
ExportOptions. - Filters the data by the specified date range.
- Routes the data to either
exportToCSVorexportToPDFbased on the requested format.
Sources: src/lib/export-service.ts:39-47
The service can generate several types of reports, including:
operationsfinancialcompliancecomprehensive
Sources: src/lib/export-service.ts:20-26
Summary
The API endpoints in VineSight form a robust backend that supports the application's core features. They provide a clear interface for data management through Supabase and enable advanced functionality by integrating with powerful external AI services. The use of Next.js Route Handlers simplifies the creation of these endpoints, while structured data types and services like ExportService ensure maintainability and scalability.