# Tanemaki — 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](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](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**. Tanemaki (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 Tanemaki 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 (Tanemaki) | 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

- **Tanemaki** = 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:

```
tanemaki/            (repo)
  packages/
    commons_core/    ← identidad, sync, Offer, Party, Pledge, confianza, discovery
  apps/
    app_seeds/       ← Tanemaki: 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 Tanemaki.

---

## 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?