tane/docs/design/usability-and-architecture.md

Tane — Usabilidad y generalización (nota de diseño)

Documento de reflexión. Lengua: español (discusión). Afecta a la estructura del primer commit de código, por eso conviene decidirlo ahora.

Dos temas que, resulta, se responden juntos: quién usa la app condiciona cómo se arquitectura.

---

Parte A — Usabilidad: de los 10 a los 80, sin dejar a nadie fuera

Principio de primer nivel, por encima de casi todo lo demás: la app debe cubrir todos los públicos a la vez — la gente del campo y la persona mayor con poca familiaridad digital y también quien gestiona un banco de semillas. No se trata de excluir a nadie, sino de que nadie se quede fuera. Personas de diseño concretas, como en g1nkgo (pensado para una hija de 10 y una madre de 80): si funciona para las dos, funciona para todos.

Cómo se reconcilia "para la niña de 10 y la abuela de 80" con "para quien lleva un banco": la superficie de entrada tiene que ser legible y amable para el que menos sabe, y la profundidad estar disponible, plegada, para el que más necesita. Eso es exactamente el progressive disclosure (§1 de data-notes.md): una sola app, simple por fuera, potente por dentro. El gestor de banco no queda fuera — obtiene toda la potencia; simplemente no se le impone al resto. Tiene que ser muy sencilla y a la vez potente, y esto no es un "nice to have": es un requisito que condiciona la arquitectura (ver Parte B).

Cómo se traduce en decisiones concretas:

• Objetivos táctiles grandes, tipografía grande y legible, alto contraste. Pensado para vista cansada y dedos de trabajo. Accesibilidad real, no de adorno.
• Icono + palabra, siempre. Nunca solo iconos (se malinterpretan), nunca muros de texto. Cada acción, un dibujo y una palabra clara.
• Cero jerga. El usuario nunca ve "accession", "CRDT", "geohash", "relay", "clave pública". Se dicen las cosas como en el campo: "mi cajón de semillas", "dar", "pedir", "cerca de ti". La complejidad técnica existe, pero es invisible.
• Foto primero. La gente mayor y del campo fotografía mejor que teclea. Una foto + un nombre hablado o corto vale más que un formulario. La cámara es la vía de entrada principal.
• El alta en 20 segundos (ya en data-notes.md §1): nombre + foto y ya. Todo lo demás, opcional y plegado.
• Sin muro de registro. La identidad se genera sola, en silencio; nada de crear cuenta, email, contraseña para empezar.
• Funciona sin conexión, sin penalización ni errores si no hay red (mucha huerta no tiene cobertura).
• Indulgente. Deshacer siempre; borrar es una "papelera" reversible (encaja con los tombstones del modelo, §4); ningún callejón sin salida destructivo.
• La navaja que reconcilia "sencilla y potente": progressive disclosure (ya decidido). La app parece simple para la abuela y despliega profundidad para quien gestiona un banco — sin ser dos apps ni dos modos visibles.
• Probar con el público real, pronto. Test con personas mayores y en una feria de intercambio, no con informáticos. La "prueba de la abuela" manda.

Consecuencia para la Parte B: como la superficie de entrada tiene que ser legible para todo el mundo, de los 10 a los 80, una app genérica de "comparte cualquier cosa" es una mala idea de producto — es menos legible que "la app de las semillas". La inclusión del público más amplio favorece productos monotema sobre un motor compartido. Eso orienta la arquitectura.

---

Parte B — Generalización: app de semillas + biblioteca distribuida de cosas

La visión de fondo: un motor genérico que permita implementar (1) esta app de semillas y (2) una biblioteca distribuida de cosas/herramientas — qué tengo, qué comparto, con costes autogestionados y red de confianza para saber si se devuelve o no. La pregunta: ¿motor común, o cada app por su lado?

El solape es enorme, y es justo la parte difícil

Lo que comparten semillas y biblioteca-de-cosas:

• Identidad descentralizada (par de claves), sincronización P2P local-first, descubrimiento por cercanía (geohash), red de confianza / reputación.
• Inventario de "lo que tengo".
• Oferta / visibilidad de "lo que comparto".
• Préstamo con devolución esperada + confianza sobre si se devuelve. Aquí está la clave: "¿me devolvió la escalera?" de la biblioteca de cosas es exactamente el "¿devolvió semilla similar?" del Plantare. El mecanismo es el mismo pagaré.

Lo que difiere es poco: el objeto de dominio (una variedad con germinación/especie vs. una herramienta con estado/depósito) y un puñado de campos. El 80% difícil es común; el 20% fácil es específico.

Prior art que lo confirma: el software de "Library of Things" (Lend Engine, myTurn, PVD Things) existe pero es todo centralizado — el hueco descentralizado es el mismo que en semillas. La segunda app también es un nicho real sin cubrir.

Tres opciones de arquitectura

Opción	Qué es	Veredicto
A. Dos apps independientes	Cada una reimplementa identidad, sync, confianza, préstamo…	❌ Duplica la parte difícil. Insostenible para un mantenedor.
B. Una app genérica "comparte lo que sea" con modos	Un solo producto que sirve para semillas, herramientas, lo que quieras	❌ Choca con la Parte A. La abuela quiere "la app de las semillas", no una plataforma genérica. Hinchazón, identidad confusa, onboarding peor.
C. Núcleo común + apps finas monotema	Un paquete reutilizable core (identidad, sync, inventario, oferta, préstamo/pagaré, confianza, descubrimiento) + apps delgadas y simples encima, cada una con su nombre e identidad	✅ Recomendada. Sin duplicar lo difícil; cada app queda legible y de un solo propósito.

La reconciliación: generaliza el MOTOR, no el PRODUCTO

Usabilidad y reutilización apuntan a la misma respuesta. Tane (semillas) y la futura app de cosas son productos separados, simples, monotema, cada uno con su nombre y su cara; por debajo comparten un motor común que resuelve una sola vez la fontanería P2P/confianza/préstamo. Generalizas donde nadie lo ve (el engine), no donde todo el mundo lo sufre (el producto).

¿Ahora o después? "Diseña para generalizar, implementa uno"

• Construye solo Tane ahora. No hagas la plataforma genérica de forma especulativa (riesgo de abstracción prematura: te sale la abstracción equivocada).
• Pero estructura el repo desde el primer commit como workspace con un paquete core/ + app_seeds/, respetando una costura de dominio limpia. Extraer más adelante la app de cosas es barato si la costura se respeta; retrofitear un motor genérico dentro de un monolito es caro.
• En core va solo lo obviamente compartido (identidad, sync, Offer, Party, confianza, Pledge/registro de préstamo). Lo específico de semillas (Species, germinación, cosecha) se queda en el dominio de semillas. Se sube más a core solo cuando la segunda app revele la forma real compartida (regla del tres — pero el núcleo P2P/confianza/pagaré es conocido-compartido de antemano, así que extraerlo ya está justificado).

Cómo generalizan las entidades (mapa)

Genérico (core)	Semillas (Tane)	Cosas (futura)
Item / holding	Variety + Lot	herramienta / objeto
Offer (+ tipo lend: devolver el mismo objeto)	gift/exchange/sale/wanted	lend/gift/sale/wanted
Pledge (promesa de devolución)	Plantare (devolver similar)	préstamo (devolver esto, con fecha)
Movement / ledger, Party, Group, confianza	igual	igual
(módulo de dominio)	Species, germinación, cosecha, cultivar	estado, depósito, coste

Nota: el Plantare es el caso semillas de un concepto genérico Pledge (promesa de devolución). Para cosas, "devolver el mismo objeto por una fecha"; para semillas, "devolver algo similar". Misma estructura firmada y bilateral.

Nombres

• Tane = el producto de semillas.
• El núcleo conviene que tenga nombre neutro. Tu organización Comunes encaja de libro ("motor del procomún"): p.ej. paquete commons_core o similar. La app de cosas tendrá su propio nombre cuando llegue.

Consecuencia técnica inmediata (por eso se decide ahora)

El primer commit de código no es "una app Flutter", sino un workspace (pub workspaces / melos) con:

tane/            (repo)
  packages/
    commons_core/    ← identidad, sync, Offer, Party, Pledge, confianza, discovery
  apps/
    app_seeds/       ← Tane: Species, germinación, cosecha, UI de semillas, i18n

Drift: tablas de core + tablas de dominio de semillas, con las migraciones versionadas (§5 del modelo) por paquete. Así, el día que exista app_things, reusa commons_core sin tocar Tane.

---

A decidir

• ¿Confirmamos la estructura workspace (commons_core + app_seeds) para el primer commit? (Recomendado.)
• ¿Nombre del paquete núcleo: commons_core, comunes_core, otro?
• ¿El tipo lend (devolver el mismo objeto) entra ya en el enum de Offer aunque en semillas casi no se use, para no migrar luego? (Probablemente sí: es aditivo y barato.)
• La "prueba de la abuela": ¿tienes a mano personas mayores / una feria donde testear los primeros prototipos?