📱 Cuaderno de Campo Apícola¶

Proyecto de App — Cliente de campo offline-first para apicultores¶

React Native + Expo. Transcipción local con Whisper. Tres capas de almacenamiento.
Funciona sola en el móvil. Se integra opcionalmente con SmallCountry.
Proyecto externo, independiente, que conecta con Corral del Viento y la comunidad apícola.

Versión 1.0 · Mayo 2026

1. Resumen Ejecutivo¶

Un apicultor experto llega a una colmena con traje, guantes y ahumador. Tiene las manos ocupadas. Posiblemente sin cobertura. Necesita saber en tres segundos: ¿qué pasó aquí la última vez?, ¿qué tengo que hacer hoy?, y registrar lo que veo ahora mismo sin escribir ni navegar menús.

Las apps existentes fallan porque priorizan la captura de datos sobre la consulta rápida, requieren internet, tienen demasiados pasos para tareas simples, o están diseñadas para gestores de explotaciones grandes, no para apicultores de campo.

El Cuaderno de Campo Apícola es una app móvil para Android e iOS que resuelve esto. Voz como entrada principal, botones grandes, contexto de la colmena antes que el formulario. Tres capas de almacenamiento independientes y combinables: solo en el teléfono, sincronizada con farmOS de SmallCountry, o compartiendo datos voluntariamente con la comunidad apícola. Con incentivo: si compartes datos con la comunidad, la app te muestra información anonimizada de los apiarios cercanos directamente en la pantalla de colmena.

Visión: Que un apicultor pueda llegar a su colmena, saber en tres segundos su historial, y registrar lo que ve sin soltar el ahumador.

2. Principios de diseño (no negociables)¶

Offline-first absoluto. Sin internet, todo funciona igual. No hay funcionalidad degradada sin cobertura.
Una mano, con guantes. Todos los elementos interactivos son botones grandes. Nada requiere precisión táctil fina.
Voz como entrada principal. El texto es secundario. El teclado es el último recurso.
Contexto antes que captura. La primera pantalla de una colmena muestra su historial, no un formulario.
Tres segundos para lo esencial. El apicultor puede saber el estado de una colmena en tres segundos desde que abre la app.
Datos del usuario, siempre. Nada se envía a ningún sitio sin consentimiento explícito. El modo local es completo y permanente.

3. Arquitectura de tres capas¶

El usuario configura en ajustes qué capas activa. Pueden combinarse libremente.

Capa 1 — Standalone (siempre activa)¶

Todos los datos en SQLite local en el teléfono
Funciona sin internet, sin cuenta, sin servidor
Exportación local a JSON/CSV en cualquier momento
Esta capa nunca se puede desactivar

Capa 2 — SmallCountry personal (opcional)¶

Sincronización con farmOS del usuario vía JSON:API
Los datos van al servidor personal del apicultor
Nadie más los ve
Configuración: URL de farmOS + token OAuth2/OIDC vía Authentik
Compatible con el módulo farm_bee extendido de Corral del Viento

Capa 3 — Comunidad (opcional, voluntaria, con incentivo)¶

Servidor centralizado en la Zona Cero de SmallCountry
El apicultor elige qué datos comparte (por defecto: nada)
Los datos compartidos son anónimos (ubicación redondeada a ~5 km)
API pública REST de lectura libre
Datasets mensuales publicados con DOI en InvenioRDM
Formato Darwin Core extendido para biodiversidad apícola
El servidor comunitario alimenta a Corral del Viento con contexto regional
Incentivo: si compartes, la app te muestra datos de los apiarios cercanos (anonimizados) directamente en la pantalla de colmena. Si no compartes, puedes acceder a los mismos datos desde la web de la Zona Cero: floraciones confirmadas en la zona, niveles de varroa regionales, patrones estacionales

App (React Native + Expo)
    │
    ├── SQLite local (siempre, offline-first)
    │
    ├── Capa 2: farmOS API (cuando hay cobertura)
    │   └── farm.corraldelviento.sc/api
    │
    └── Capa 3: Servidor comunitario (cuando hay WiFi)
        └── Zona Cero → API pública + InvenioRDM

4. Stack técnico¶

React Native + Expo SDK 51+
├── expo-av              → grabación de audio por nodo
├── react-native-whisper → transcripción local offline
│   └── Modelo: whisper-large-v3-turbo (809 MB)
│   └── Solo castellano (mejora precisión apícola)
│   └── Prompt inicial: contexto apícola
├── expo-sqlite          → base de datos local
├── expo-location        → GPS para geolocalizar inspección
├── expo-camera          → foto por nodo (opcional)
├── expo-notifications   → alertas locales de revisión
└── @tanstack/query      → sync con servidores en background

Por qué React Native + Expo: - Una codebase para Android e iOS - Expo maneja builds sin necesidad de Mac para iOS en desarrollo - react-native-whisper tiene soporte activo y compilación nativa de whisper.cpp - Ecosistema maduro para apps offline-first

Por qué whisper-large-v3-turbo: - 809 MB — razonable en móviles actuales - Solo castellano: el modelo puede especializarse en vocabulario apícola - Velocidad adecuada en gama media (~2-3 segundos por transcripción) - Calidad excelente para terminología técnica (varroa, oxálico, melojo)

El parser apícola (transcripción → campos)¶

Whisper transcribe. El parser convierte la transcripción en campos estructurados. No necesita LLM — un diccionario especializado es más rápido, más fiable y funciona 100% offline:

const DICCIONARIO_APICOLA = {
  reina: {
    vista:    ['reina presente', 'veo la reina', 'reina vista', 'localizada'],
    ausente:  ['sin reina', 'huérfana', 'no veo reina', 'falta la reina'],
    dudosa:   ['reina dudosa', 'no localizo la reina']
  },
  varroa: {
    ninguna:  ['sin varroa', 'no hay varroa', 'varroa cero', 'limpio'],
    baja:     ['poca varroa', 'varroa baja', 'varroa escasa'],
    media:    ['varroa media', 'bastante varroa', 'varroa moderada'],
    alta:     ['mucha varroa', 'varroa alta', 'varroa crítica']
  },
  tratamiento: {
    oxalico:  ['oxálico', 'ácido oxálico', 'sublimación'],
    formico:  ['fórmico', 'ácido fórmico', 'apilife'],
    timol:    ['timol', 'apiguard', 'thymovar']
  },
  celdas_reales: [
    'celdas reales', 'hay reales', 'veo reales', 'preparando enjambre'
  ]
}

El prompt inicial para Whisper que mejora la precisión:

"Inspección apícola en español. Vocabulario: colmena, reina, cría, varroa,
oxálico, fórmico, timol, enjambre, celda real, opérculo, alza, cuadro,
melojo, cantueso, retama, tomillo, Gredos, La Vera, Cáceres."

5. Pantallas principales¶

5.1 Inicio — Lista de colmenas¶

🐝 Mis colmenas                    [+ Nueva]
───────────────────────────────────────────
🟢 Solana 7                    hace 3d
   Reina vista · Cría buena
   ⚠️ Revisar pronto

🟡 Corcho grande               hace 8d
   Sin reina confirmada
   ⚠️ Requiere atención

🔴 Bajo el roble               hace 21d
   ⚠️ Sin inspección reciente

🟢 Kenya 1                     hace 5d
   Todo normal

El color refleja urgencia: verde (bien), amarillo (vigilar), rojo (atención requerida).

5.2 Colmena — El contexto¶

← Solana 7
Langstroth · Abeja Negra Ibérica
Reina 2024 · Marcada (verde)
───────────────────────────────────────────
ÚLTIMA INSPECCIÓN — hace 3 días

Reina vista ✓   Cría compacta ✓
Varroa: baja    Miel: suficiente

PENDIENTE
• Valorar alza si sigue creciendo
• Tratamiento oxálico en 2 sem

HISTORIAL
02/05 · Reina vista, cría buena
24/04 · Tratamiento oxálico

[  INICIAR INSPECCIÓN  ]  ← botón grande abajo

5.3 Inspección guiada — Árbol de decisión¶

Para principiantes o cuando se quiere ser exhaustivo. La app guía nodo a nodo con 7 secciones: Reina → Cría → Población → Reservas → Sanidad → Espacio → Acciones. Cada nodo tiene:

Pregunta clara en texto grande
Botón de micrófono (grabar observación sobre ese punto)
2-4 botones de respuesta rápida
Ayuda contextual (desactivable)
Botón "saltar" siempre visible

Inspección · Solana 7 · 1/7
─────────────────────────────────

    ¿Ves a la reina?

 ℹ️ Busca el abdomen más alargado.
   Suele estar rodeada de abejas.

 [  🎙️  Grabar nota  ]

 [   SÍ   ] [  NO  ] [ NO SÉ ]

             [Saltar →]

5.4 Inspección rápida — Modo experto¶

Una sola pantalla con audio global:

Inspección rápida · Solana 7
─────────────────────────────────
 [  🎙️  HABLAR  ]

 Reina  [✓][?][✗]   Cría [✓][~][✗]
 Miel   [↑][=][↓]   Varroa [·][!][!!]
 Ánimo  [😊][😐][😠]

 Hecho hoy:
 [alza ✓] [alimentación] [tto]

 Próxima: [1s][2s][1m][+]

      [  GUARDAR  ]

Whisper transcribe el audio y el parser rellena los botones automáticamente. El apicultor solo confirma o corrige.

5.5 Ajustes¶

ALMACENAMIENTO
  ✓ Local (siempre activo)
  ○ SmallCountry personal → URL farmOS, token
  ○ Comunidad apícola → qué datos comparto

MODO DE INSPECCIÓN
  ○ Guiado   ● Rápido
  Mostrar ayudas: ✓

DATOS
  [Exportar → JSON] [Exportar → CSV]

6. Integración con SmallCountry (Capa 2)¶

Con farmOS¶

La app usa la JSON:API de farmOS directamente. Sincronización bidireccional en background:

Operación	Endpoint farmOS
Crear inspección	`POST /api/log/activity`
Listar colmenas	`GET /api/asset/animal?filter[status]=active`
Registrar tratamiento	`POST /api/log/input`

Si farmOS no está disponible, los datos se guardan en SQLite y se sincronizan al reconectar.

Con Victoria Metrics (sensores)¶

Si la colmena tiene sensores físicos (báscula, temperatura), la app consulta los datos recientes vía PromQL y muestra un mini-gráfico en la pantalla de colmena:

query_range?query=colmena_peso_kg{colmena="solana7"}&start=-7d&step=1h

7. Servidor comunitario (Capa 3)¶

Qué es¶

Una API REST pública alojada en la Zona Cero de SmallCountry. Acepta datos de inspecciones anonimizadas de cualquier apicultor con la app. Publica datasets abiertos con DOI en InvenioRDM. Alimenta a Corral del Viento con contexto regional.

Endpoints públicos (lectura libre, sin auth)¶

Endpoint	Datos
`GET /api/v1/floraciones?zona=gredos&radio=50km`	Floraciones reportadas en la zona
`GET /api/v1/varroa?zona=la_vera&mes=mayo`	Niveles medios de varroa en la zona
`GET /api/v1/calendario?lat=40.1&lon=-5.7`	Calendario apícola basado en datos históricos
`GET /api/v1/datasets`	Datasets publicados con DOI

Lo que aporta a Corral del Viento¶

«Esta semana, 3 apicultores de La Vera reportan varroa media-alta»
«Floración de cantueso confirmada en radio 20 km desde el 3 de mayo»
«Enjambrazón activa en la comarca — revisar colmenas con celdas reales»

Contexto que ningún apicultor puede tener solo con sus propias colmenas.

Privacidad: opt-in con incentivo¶

El apicultor elige exactamente qué comparte. Por defecto: nada. Opciones: - Niveles de varroa (sin identificar colmena ni apicultor) - Floraciones observadas (ubicación redondeada a ~5 km) - Fechas de enjambrazón (solo sí/no, sin detalles)

Incentivo por compartir: si el apicultor activa la Capa 3 y comparte datos, la app le devuelve información de los apiarios más cercanos directamente en la pantalla de colmena, sin tener que salir a la web de la Zona Cero ni usar otra app:

┌─────────────────────────────────┐
│ 🌍 Tu zona — datos comunitarios │
│                                 │
│ Radio 20 km · 3 apicultores     │
│                                 │
│ Varroa: 🟡 media en la zona     │
│ Floración: 🌸 cantueso activo   │
│ Enjambrazón: ⚠️ activa          │
│                                 │
│ "Esta semana, 3 apicultores de  │
│  La Vera reportan varroa media. │
│  Cantueso en flor desde el 3/5" │
└─────────────────────────────────┘

Toda la información es anónima: no se muestra quién, qué colmena ni coordenadas exactas. Solo tendencias agregadas de la zona.

Si NO comparte datos: puede acceder a la misma información, pero a través de la web pública de la Zona Cero (datos.elsalto.sc) o conectando a la API desde otra herramienta. La app no se la muestra directamente. Esto incentiva la contribución sin obligar — el que aporta recibe contexto en el mismo lugar donde trabaja.

8. Integración con SmallCountry¶

8.1 Roles implicados¶

Rol	Función
Melissa — Colmenas y miel	Usuaria principal de la app en campo
Hefesto — Infraestructura	Despliegue del servidor comunitario en Zona Cero

8.2 Servicios de SmallCountry que usará¶

Recurso	Para qué
farmOS	Backend de registros apícolas (Capa 2)
Authentik	OAuth2/OIDC para autenticación de la app
Victoria Metrics	Datos de sensores de colmena (peso, temperatura)
n8n	Middleware de anonimización antes de InvenioRDM
InvenioRDM	Publicación de datasets comunitarios con DOI
ntfy	Notificaciones de alertas (Schwarmalarm, varroa)
Proyecto Clima	Datos meteorológicos para predicción de floración
Zona Cero	Alojamiento del servidor comunitario (público, sin auth)

Para el administrador

Servidor comunitario¶


LXC	Por asignar — Zona Cero
Dominio	`api.elsalto.sc`
Tier	C — Conveniente
Stack	FastAPI (Python) + PostgreSQL + PostGIS
ZFS dataset	`rpool/datos/comunidad-apicola/`
Backup	PBS diario + ZFS snapshot @15min

App móvil¶

Repositorio: Forgejo (corral-del-viento/app-colmena)
Builds: Expo EAS Build (Android + iOS)
Distribución: APK directo + TestFlight (evita tasas de tiendas)
Actualizaciones: OTA vía Expo Updates

Para el arquitecto

Esquema de integración¶

flowchart TB
    subgraph App["📱 App móvil"]
        SQLite[(SQLite local)]
        Whisper[Whisper.cpp<br/>transcripción]
        Parser[Parser apícola]
    end

    subgraph SmallCountry["⚙️ SmallCountry"]
        farmOS[farmOS<br/>JSON:API]
        Authentik[Authentik<br/>OAuth2/OIDC]
        VictoriaMetrics[Victoria Metrics<br/>sensores]
        n8n[n8n<br/>anonimización]
    end

    subgraph ZonaCero["🌐 Zona Cero"]
        API[API comunitaria<br/>FastAPI + PostGIS]
        InvenioRDM[InvenioRDM<br/>datasets DOI]
    end

    App -->|Capa 2| farmOS
    App -->|Capa 3| API
    Authentik -->|auth| farmOS
    Authentik -->|auth| API
    VictoriaMetrics -->|PromQL| App
    API --> n8n
    n8n --> InvenioRDM
    InvenioRDM -->|DOI público| ZonaCero

Orquestación¶

Componente	Path / Nombre
App móvil	`corral-del-viento/app-colmena/` (Forgejo)
Servidor comunitario	`roles/comunidad-apicola/`
Playbook	`deploy-comunidad-apicola.yml`
Forgejo Actions	`.forgejo/workflows/comunidad-apicola.yml`

9. Hoja de Ruta¶

Fase 1 — MVP de campo¶

[ ] Lista de colmenas con estado visual
[ ] Pantalla de colmena con historial y pendientes
[ ] Inspección rápida con audio global
[ ] Transcripción local con Whisper large-v3-turbo (castellano)
[ ] Parser apícola básico (reina, varroa, cría, miel)
[ ] SQLite local
[ ] Sin servidor, sin cuenta, sin internet

Fase 2 — Modo guiado¶

[ ] Árbol de decisión completo (7 nodos: reina, cría, población, reservas, sanidad, espacio, acciones)
[ ] Audio por nodo individual
[ ] Ayudas contextuales para principiantes
[ ] Registro de floraciones
[ ] Alertas locales de revisión

Fase 3 — Conexión con SmallCountry (Capa 2)¶

[ ] Sync bidireccional con farmOS JSON:API
[ ] Autenticación OAuth2/OIDC vía Authentik
[ ] Lectura de datos de sensores desde Victoria Metrics
[ ] Mini-gráfico de peso y temperatura en pantalla de colmena

Fase 4 — Comunidad (Capa 3)¶

[ ] Desplegar servidor comunitario en Zona Cero
[ ] Configuración granular de datos a compartir
[ ] Sync con servidor comunitario
[ ] Visualización de datos de la zona (floraciones, varroa regional)
[ ] Publicación automática mensual de datasets con DOI en InvenioRDM

10. Lo que NO debe hacer la app¶

❌ No requerir registro ni cuenta para funcionar
❌ No enviar datos a ningún servidor sin consentimiento explícito
❌ No tener menús de más de dos niveles de profundidad
❌ No usar teclado como entrada principal
❌ No fallar si no hay internet
❌ No perder datos nunca (SQLite es la fuente de verdad siempre)
❌ No intentar ser un ERP de gestión de explotación
❌ No competir con farmOS — la app es el cliente de campo, farmOS es el servidor

11. Notas Finales¶

El Cuaderno de Campo Apícola no compite con Tierras Apícolas, Hiveeyes ni con farmOS. Es la capa de campo que conecta al apicultor con su colmena y, opcionalmente, con su infraestructura SmallCountry y con la comunidad.

La decisión de diseño más importante ya está tomada: la app funciona sola. SmallCountry la enriquece pero no la condiciona. Un apicultor puede usar la app para siempre en modo standalone; otro puede sincronizarla con su farmOS; un tercero puede además compartir datos con la comunidad. Las tres opciones son válidas y no excluyentes.

Próximo paso: Construir el MVP con React Native + Expo: lista de colmenas, inspección rápida con audio, transcripción local, SQLite.

Secciones relacionadas¶

← Proyectos