Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Vinesight is a sophisticated Progressive Web App (PWA) engineered to serve as a digital companion for grape farmers in India. The architecture is built upon a modern technology stack, emphasizing a reactive user experience, robust data management, and advanced AI-driven insights. The system is designed to be scalable and maintainable, leveraging a serverless backend, a component-driven frontend, and a suite of integrated AI services.
The core of the application is a Next.js 15 frontend that communicates with a Supabase backend for database operations and authentication. It integrates multiple AI providers for features like disease detection and conversational assistance. The architecture supports multi-language capabilities (English, Hindi, Marathi) and is designed for offline functionality, making it a practical tool for farmers in diverse environments.
Core Technology Stack
The application is built with a selection of modern frameworks and libraries to ensure performance, scalability, and a rich user experience.
Sources: AGENTS.md, package.json, context/PRD.md:213-229
The following diagram illustrates the high-level components of the Vinesight architecture.
| Component | Technology/Service - | Description - |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Framework | Next.js 15, React 19, TypeScript - |
| Database | Supabase (PostgreSQL) with Row Level Security - |
| UI | shadcn/ui, Radix UI, Tailwind CSS - |
| AI Integration | OpenAI, Google AI, Groq, TensorFlow.js (for Computer Vision) - |
- PWA |
next-pwafor offline support,dexiefor client-side database - |
| Internationalization|i18next,react-i18next- |
| Analytics |@vercel/analytics, Google Analytics - |
Sources: AGENTS.md:13-20, package.json, src/app/layout.tsx:10-13
Frontend Architecture
The frontend is built with Next.js 15 and the App Router, providing a modern, server-component-first architecture.
Sources: AGENTS.md:13, package.json:35
Key Directories
| Directory | Purpose |
|---|---|
src/app/ | Contains application pages and layouts (App Router) |
src/components/ | Reusable UI components (e.g., shadcn/ui) |
src/lib/ | Shared libraries and services (e.g., Supabase, AI) |
src/hooks/ | Custom React hooks |
Source: AGENTS.md:21
UI and Styling
The UI is constructed using shadcn/ui components, which are built on top of Radix UI primitives and styled with Tailwind CSS. This provides a highly customizable and accessible component library. Conditional class names are managed using the clsx and tailwind-merge utilities.
Sources: AGENTS.md:15, package.json:20-47
Internationalization (i18n)
The application supports multiple languages (English, Hindi, and Marathi) through the i18next and react-i18next libraries. A central configuration file defines the translation resources for each language.
Sources: AGENTS.md:18, src/lib/i18n.ts, package.json:42, 60
The i18n resource structure is organized by language and feature, as shown below.
Source: src/lib/i18n.ts:5-460
The I18nProvider wraps the root layout, making the translation context available throughout the application.
Source: src/app/layout.tsx:160
Progressive Web App (PWA) & Offline Support
Vinesight is a PWA, enabling installation on user devices and providing offline capabilities. This is achieved using next-pwa. For client-side storage, dexie (a wrapper for IndexedDB) is used, allowing for robust offline data logging and access.
Sources: AGENTS.md:17, package.json:43, 56
Analytics and SEO
The application is configured for comprehensive analytics and search engine optimization.
- Analytics: Integrates
@vercel/analyticsand Google Analytics. - SEO: The root layout (
src/app/layout.tsx) defines extensive metadata, includingtitle,description,keywords, Open Graph tags, Twitter cards, and JSON-LD manifest for rich search results. It also includes verification for Google Search Console.
Source: src/app/layout.tsx:41-115, 164-165
Backend and Database Architecture
The backend is powered by Supabase, providing a suite of serverless tools including a PostgreSQL database, authentication, and real-time capabilities.
Source: AGENTS.md:14
Database Schema
The database is designed to support core farm management as well as advanced AI-driven features. It uses PostgreSQL with Row Level Security (RLS) enabled to ensure data privacy and user-specific access control. The schema includes tables for managing farms, user profiles, AI recommendations, predictions, and more.
Sources: AGENTS.md:14, 30, CLAUDE.md:27-123
The following ER diagram shows the key tables and their relationships for the advanced AI features.
Source: CLAUDE.md:27-123
Key Database Tables
| Table | Description |
|---|---|
farms | Core table for storing farm details like name, area, and grape variety. |
farmer_ai_profiles | Stores user-specific AI personalization data, such as risk tolerance and decision patterns. |
ai_task_recommendations | Contains AI-generated tasks for farmers, including priority, reasoning, and status. |
pest_disease_predictions | Logs predictive alerts for pests and diseases, including risk scores and prevention windows. |
profitability_analyses | Stores results of financial analysis, including expenses, ROI, and optimization opportunities. |
market_intelligence | Caches market data like price forecasts and demand trends. |
community_insights | Anonymized data from top-performing farms to share successful practices. |
ai_conversation_context | Maintains long-term memory for the AI chat assistant to provide contextual conversations. |
Source: CLAUDE.md:27-123, context/TYPES_AND_INTERFACES.md
Authentication and Security
Authentication is handled by Supabase Auth. All new database tables are protected with Row Level Security (RLS) policies, ensuring that users can only access and manage their own data.
Sources: AGENTS.md:32, CLAUDE.md:120-123, 442-481
AI and Services Architecture
Vinesight integrates a multi-provider AI architecture to deliver its smart farming features.
Source: AGENTS.md:16
AI Service Integration
- Computer Vision: Utilizes
@tensorflow/tfjsfor client-side image processing, enabling features like AI-powered disease detection directly in the browser. - Conversational AI: Leverages the OpenAI API for the AI chatbot assistant, with support for natural language processing in English, Hindi, and Marathi. Other providers like Google AI and Groq are also part of the stack.
- Voice Interface: Implements the browser's Web Speech API (
SpeechRecognition,SpeechSynthesis) for hands-free operation and accessibility.
Sources: AGENTS.md:16, context/PRD.md:221-227, package.json:32, 41, 57
AI Feature Flow: Disease Detection
The following sequence diagram illustrates the process for the AI-powered disease detection feature.
Source: context/PRD.md:83-90, 221-227
Conclusion
The architecture of Vinesight is thoughtfully designed to create a robust, intelligent, and user-friendly platform for modern grape farming. By combining a Next.js PWA with the power of Supabase and a flexible multi-provider AI backend, the system is well-equipped to deliver real-time, data-driven insights. The emphasis on offline capability, multi-language support, and strong data security through RLS makes it a practical and trustworthy tool for its target audience. The modular structure, with clear separation of concerns between UI, services, and data, provides a solid foundation for future development and the integration of more advanced AI capabilities as outlined in the project's roadmap.