AgroVision Intelligence：尼加拉瓜多源农业智能处方平台

🌱 AgroVision Intelligence

Plataforma prescriptiva de inteligencia agrícola multifuente para cultivos estratégicos de Nicaragua.

De la evidencia multifuente a la acción agrícola inteligente
Imagen + clima + sensores + historial + mapping + capa satelital simulada → evidencia → riesgo → recomendación accionable.

Equipo: AgroVision · Hackathon Nacional Nicaragua 2026 · “10 años, Siempre Más Allá”

Tabla de Contenidos

• Desafío Principal
• Problema y Propuesta de Valor
• Arquitectura
• Flujo Prescriptivo
• Stack Tecnológico
• Guía deInstalación
• Endpoints principales
• Arquitectura
• Contrato de respuesta API
• Funcionalidades del MVP
• Escalabilidad y Sostenibilidad
• Alcance y Límites
• Validación antes de PR
• Nuestro Equipo

🏆 Desafío Principal

AgroVision Intelligence convierte datos agrícolas dispersos en evidencia técnica, riesgo por zona y recomendaciones accionables para pequeños y medianos productores.

💡 Problema y Propuesta de Valor

Contexto del problema

En el sector agropecuario nacional, muchos productores toman decisiones críticas con información fragmentada, observación manual y baja trazabilidad. El problema no es únicamente medir datos como temperatura o humedad; el problema real es que esos datos rara vez se convierten en decisiones operativas claras.

Propuesta de valor

AgroVision Intelligence es una plataforma web prescriptiva que integra:

El sistema transforma esa información en:

EvidenceItem[] → RiskAssessment → ZoneInsight → Alert → Recommendation → Report

Principio ético

AgroVision no reemplaza al productor ni al técnico agrícola. Su función es apoyar la toma de decisiones con información organizada, visual, explicable y accionable.

La IA visual se presenta como detección preliminar de señales compatibles con estrés o deterioro del cultivo. No se presenta como diagnóstico fitosanitario definitivo (al menos no en esta etapa del proyecto).

🏗️ Diagrama de Arquitectura

flowchart TD
    USER["Usuario<br/>Productor ·  Ing. Agrónomo de Campo · Analista Agrícola"] --> UI["Frontend React + Vite<br/>Dashboard · Mapping · Vision AI · Crops · Alerts · Recommendations"]

    UI --> API["Backend API<br/>Express + TypeScript"]

    API --> APP["App Router API<br/>/api/*"]

    APP --> DASH["Dashboard Module"]
    APP --> CROPS["Crops Module"]
    APP --> MAP["Mapping Module"]
    APP --> VEG["Vegetation Module"]
    APP --> VISION["Vision Module"]
    APP --> ANALYSIS["Analysis Module"]
    APP --> RISK["Risk Module"]
    APP --> ALERTS["Alerts Module"]
    APP --> RECS["Recommendations Module"]
    APP --> REPORTS["Reports Module"]
    APP --> WEATHER["Weather Module"]

    CROPS --> CROP_PROFILES["CropProfile Rules<br/>Cultivos nacionales"]
    MAP --> MAP_ENGINE["Mapping Engine<br/>Trayectoria · Eventos · Detecciones"]
    VEG --> VEG_INDEX["Vegetation Indices<br/>NDVI · NDWI · GNDVI simulados"]
    WEATHER --> WEATHER_DATA["Weather Mock / Future API"]
    VISION --> AI_PROXY["Backend Vision Service"]
    AI_PROXY --> AI_SERVICE["AI Service<br/>FastAPI + OpenCV"]
    AI_SERVICE --> VISUAL_METRICS["VisualMetrics<br/>Predicción · Confianza · Explicación"]

    CROP_PROFILES --> CORE["Analysis Core"]
    MAP_ENGINE --> CORE
    VEG_INDEX --> CORE
    WEATHER_DATA --> CORE
    VISUAL_METRICS --> CORE
    TELEMETRY["Sensors / Telemetry Mock"] --> CORE
    HISTORY["History / Reports"] --> CORE

    CORE --> EVIDENCE["EvidenceItem[]<br/>Fuente · Métrica · Estado · Explicación"]
    EVIDENCE --> RISK
    RISK --> ZONE["ZoneInsight<br/>Riesgo final · Score · Causa · Acción"]
    ZONE --> ALERTS
    ZONE --> RECS
    ZONE --> DASH
    ZONE --> REPORTS

    API --> DB["PostgreSQL + Prisma<br/>Persistencia futura / modelos reales"]
    API --> MOCKS["Mocks de simulación<br/>MVP reproducible"]

Loading

🔁 Flujo Prescriptivo del Sistema

sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant B as Backend API
    participant AI as AI Service
    participant R as Risk Engine
    participant D as Dashboard

    U->>F: Sube imagen / consulta dashboard
    F->>B: Solicita análisis o datos prescriptivos
    B->>AI: Envía imagen y CropType
    AI-->>B: VisionPrediction + VisualMetrics + confidence
    B->>B: Normaliza como VisionInspection
    B->>B: Fusiona visión + clima + vegetación + mapping + historial
    B->>R: Envía EvidenceItem[]
    R-->>B: RiskAssessment
    B-->>F: ZoneInsight + Alert + Recommendation
    F-->>D: Renderiza riesgo, evidencia y acción sugerida

Loading

⚙️ Stack Tecnológico

🤖 Agente de Inteligencia Artificial

Rol del agente

El componente de IA de AgroVision se divide en dos capas:

Clasificaciones soportadas

HEALTHY
WATER_STRESS
CHLOROSIS
DRY_AREA
LEAF_SPOT
UNKNOWN

Métricas visuales esperadas

Ingeniería de prompts aplicada

AgroVision no depende de un LLM para funcionar. Sin embargo, aplica principios de ingeniería de prompts a nivel de diseño de respuestas, plantillas prescriptivas y comunicación de recomendaciones:

Ejemplo de salida IA

{
  "prediction": "WATER_STRESS",
  "confidence": 0.87,
  "visualMetrics": {
    "greenCoveragePercentage": 62,
    "dryAreaPercentage": 21,
    "chlorosisSuspected": false,
    "leafSpotSuspected": false,
    "stressPatternDetected": true
  },
  "explanation": "Se detecta reducción de cobertura verde y presencia moderada de zonas secas."
}

Uso responsable

🛠️ Guía de Instalación

Requisitos previos

Variables de entorno

Crear los siguientes archivos según el módulo que se va a ejecutar.

.env.example en raíz

# URL base del backend para referencia general
VITE_API_BASE_URL=http://localhost:3000/api

# URL local del servicio IA
AI_SERVICE_URL=http://localhost:8000

# Entorno de ejecución
NODE_ENV=development

backend/.env.example

# Puerto del backend Express
PORT=3000

# Base de datos PostgreSQL usada por Prisma
# Reemplazar user, password, host, port y database por valores locales
DATABASE_URL="postgresql://user:password@localhost:5432/agrovision"

# URL interna del AI Service
AI_SERVICE_URL=http://localhost:8000

# Entorno del backend
NODE_ENV=development

# Secreto para JWT si se habilita autenticación
JWT_SECRET="replace-with-secure-secret"

frontend/.env.example

# API base consumida por Vite
VITE_API_BASE_URL=http://localhost:3000/api

ai-service/.env.example

# Puerto del servicio IA
AI_SERVICE_PORT=8000

# Entorno del servicio IA
AI_ENV=development

# Ruta local opcional para modelos
MODEL_PATH=./models

Instalación local

1. Clonar el repositorio

git clone https://github.com/luis-hdz7/AgroVision.git
cd AgroVision

2. Instalar dependencias del backend

npm --prefix backend install

3. Instalar dependencias del frontend

npm --prefix frontend install

4. Crear entorno virtual para AI Service

cd ai-service
python -m venv .venv

Windows:

.venv\Scripts\activate

Linux / macOS:

source .venv/bin/activate

Instalar dependencias:

pip install -r requirements.txt
cd ..

Si requirements.txt aún no existe, crear primero el archivo dentro de ai-service/.

Prisma y base de datos

Desde la raíz:

cd backend
npx prisma generate
npx prisma migrate dev
cd ..

Si se ejecuta únicamente con mocks para demo local, las migraciones pueden omitirse temporalmente.

Levantar servicios

Backend

npm run dev:backend

Backend esperado:

http://localhost:3000

Frontend

En otra terminal:

npm run dev:frontend

Frontend esperado:

http://localhost:5173

AI Service

En otra terminal:

cd ai-service

Windows:

.venv\Scripts\activate

Linux / macOS:

source .venv/bin/activate

Ejecutar:

uvicorn main:app --reload --port 8000

AI Service esperado:

http://localhost:8000

Comandos rápidos del monorepo

📡 Endpoints Principales

📂 Arquitectura de Carpetas

AgroVision/
│
├── README.md
├── package.json
├── .gitignore
├── .env.example
│
├── backend/
│   ├── package.json
│   ├── tsconfig.json
│   ├── prisma.config.ts
│   ├── prisma/
│   │   └── schema.prisma
│   │
│   └── src/
│       ├── app.ts
│       ├── server.ts
│       │
│       ├── shared/
│       │   ├── responses/
│       │   │   └── apiResponse.ts
│       │   ├── contracts/
│       │   ├── middlewares/
│       │   ├── config/
│       │   ├── types/
│       │   └── utils/
│       │
│       ├── data/
│       │   └── mocks/
│       │
│       └── modules/
│           ├── mapping/
│           ├── dashboard/
│           ├── crops/
│           ├── vegetation/
│           ├── analysis/
│           ├── risk/
│           ├── alerts/
│           ├── recommendations/
│           ├── vision/
│           ├── weather/
│           ├── reports/
│           ├── farms/
│           ├── fields/
│           ├── sensors/
│           ├── telemetry/
│           ├── missions/
│           ├── field-notebook/
│           └── sync/
│
├── frontend/
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   │
│   └── src/
│       ├── main.tsx
│       ├── app/
│       ├── shared/
│       │   ├── api/
│       │   ├── components/
│       │   ├── styles/
│       │   ├── types/
│       │   └── utils/
│       │
│       └── features/
│           ├── dashboard/
│           ├── mapping/
│           ├── crops/
│           ├── vision-ai/
│           ├── alerts/
│           ├── recommendations/
│           ├── reports/
│           ├── field-notebook/
│           ├── missions/
│           └── sync-status/
│
├── ai-service/
│   ├── main.py
│   ├── requirements.txt
│   └── app/
│       ├── schemas.py
│       ├── vision_analyzer.py
│       ├── model_loader.py
│       ├── training/
│       └── utils/
│
├── contracts/
│   ├── AGROVISION_DATA_CONTRACT.md
│   └── AGROVISION_INTELLIGENCE_EXTENSION.md
│
└── docs/

🔐 Contrato de Respuesta API

Todos los endpoints deben responder con la misma estructura base:

interface ApiResponse<T> {
  success: boolean;
  data: T | null;
  message?: string;
  error?: string;
  timestamp: string;
}

Contratos centrales

🧭 Funcionalidades del MVP

🚀 Escalabilidad y Sostenibilidad Técnica

⚠️ Alcance y Límites del MVP

✅ Validación antes de Pull Request

Paquete de preclasificación

El estado verificable de la demo se mantiene en:

• docs/evidence/EVIDENCE_CHECKLIST_PRECLASIFICACION.md: responsables, estados, ubicaciones y bloqueos.
• docs/backend/ideathon-demo-evidence-map.md: recorrido oficial de la demo.
• docs/backend/SMOKE_TEST_RESULTS.md: endpoints comprobados y condiciones de ejecución.
• docs/reports/REPORTS_STRUCTURE.md: contrato real del reporte prescriptivo.

El Notebook se demuestra mediante su endpoint y JSON, ya que no tiene una pantalla dedicada. La visión se presenta como análisis preliminar simulado, no como un modelo agrícola entrenado al menos no en esta fase del proyecto aún.

git status --short
npm run build:backend
npm run build:frontend

Flujo recomendado:

git checkout master
git pull origin master
git checkout -b feat/nombre-del-cambio

Después de trabajar:

git add ruta-del-cambio
git commit -m "feat(modulo): descripcion clara"
git push -u origin feat/nombre-del-cambio

👥 Equipo

📬 Contacto

🌱 AgroVision Intelligence

No se trata solo un dashboard agrícola genérico. Es una plataforma prescriptiva que convierte evidencia multifuente tangibles en decisiones agrícolas accionables, con valor real y resultados medibles.