Glosario y Ubiquitous Language
Este glosario define los términos clave y el Ubiquitous Language de Bodibly, la app de fitness para tracking en el gimnasio. Su objetivo es alinear la comunicación y el entendimiento entre desarrolladores, diseñadores y cualquier miembro del equipo.
Este documento define conceptos y decisiones de dominio. Los contratos técnicos — shapes de requests y responses, endpoints, códigos de estado — viven en la referencia OpenAPI del servidor, no aquí.
¿Por qué un glosario?
Un glosario y un lenguaje ubicuo (Ubiquitous Language) ayudan a evitar malentendidos y aseguran que todos los conceptos importantes de la aplicación tengan una definición clara y compartida.
Catálogo de entrenamiento
Equipo (Equipment)
Tipo de equipamiento que un ejercicio requiere. Ejemplo: barra, mancuerna, peso corporal, banda elástica, etc.
Patrón de Movimiento (Movement Pattern)
Forma general en la que se ejecuta un ejercicio, como empuje, jalón, rotación interna, rotación externa, etc.
Grupo Muscular (Muscle Group)
Conjunto grande de músculos relacionados, como piernas, espalda, brazos, pecho, etc.
Músculo (Muscle)
Músculo específico que pertenece a un grupo muscular. Ejemplo: cuádriceps (pertenece a piernas), pectoral mayor (pertenece a pecho).
Disciplina (Discipline)
Estilo o categoría de práctica al que pertenece un ejercicio. Ejemplos: fuerza, culturismo, calistenia, crossfit, powerlifting, halterofilia, cardio, movilidad. Un mismo ejercicio puede pertenecer a varias disciplinas (por ejemplo, una sentadilla con barra es a la vez fuerza, culturismo, crossfit y powerlifting).
Tipo de Medición de Set (Set Measurement Type)
Forma en la que se registra un set de un ejercicio. Define qué datos pide la app al usuario al loggearlo. Ejemplos: peso + repeticiones (press de banca), solo repeticiones (dominadas con peso corporal), solo tiempo (plancha), distancia + tiempo (correr o remar), peso + tiempo (cargas con peso). Cada tipo declara qué campos son obligatorios y cuáles permite opcionalmente — un mismo ejercicio puede ser por tiempo y aún así aceptar peso adicional (ver Carga Opcional).
Tipo de Set (Set Type)
Clasificación de un set según la intención del usuario al ejecutarlo. Cuatro valores iniciales: Calentamiento (carga submáxima de preparación, se excluye de PRs y volúmenes), Set de Trabajo (entrenamiento estándar, valor por defecto), Drop Set (set adicional con carga reducida tras un set de trabajo) y Hasta el Fallo (llevado hasta no poder completar otra repetición). Permite que el usuario revise su historial sabiendo cuál era el objetivo de cada set.
Carga Opcional
Algunos tipos de medición permiten añadir peso opcionalmente aunque no lo requieran (por ejemplo, un plank o una dominada se pueden hacer con peso adicional). El tipo de medición del ejercicio es quien lo decide; el cliente muestra el campo como opcional cuando aplica.
Ejercicio (Exercise)
Unidad mínima de trabajo físico que un usuario puede ejecutar y registrar. Combina un Patrón de Movimiento, un Equipo principal sugerido (con alternativas válidas), uno o más Músculos involucrados (con rol primario o secundario), un Tipo de Medición de Set y una o más Disciplinas a las que pertenece.
Existen dos clases:
- De catálogo — curados por Bodibly (~1300 hoy, sembrados del dataset GymVisual), con artwork y clips de demostración. Un ejercicio de catálogo nunca se borra: se archiva, porque el historial de entrenamientos lo referencia para siempre.
- Custom — creados por el usuario, visibles solo para él. Nacen en el teléfono (offline) o vía la API, y viajan por sync como cualquier otro dato del usuario.
El code de un ejercicio de catálogo es su identificador histórico estable: nunca se renombra, porque es lo que el historial de sesiones y el índice de búsqueda tienen anclado.
Artwork de Ejercicio
Imagen ilustrativa de un ejercicio de catálogo, servida desde el CDN. Puede llevar variantes por género (masculina / femenina): el cliente elige la variante según el género del usuario, porque el género vive en el usuario y no en el ejercicio — elegir en el servidor haría del catálogo un dato por-usuario. Los ejercicios custom no llevan artwork.
Clip de Demostración (Instruction Media)
Video o GIF corto que muestra cómo se ejecuta un ejercicio de catálogo, con su atribución de licencia (hoy, clips de GymVisual). Solo lectura, gestionado por el seed del catálogo. Un clip puede declarar el género del modelo que aparece; si no lo declara, es unisex y se muestra a todos.
Músculo Primario (Primary Muscle)
Motor principal de un ejercicio. Es el músculo que realiza el mayor trabajo durante el movimiento (por ejemplo, el pectoral mayor en el press de banca). Un ejercicio puede tener varios músculos primarios (una sentadilla es cuádriceps y glúteos a la vez) — el orden en que se declaran es dato del catálogo, y el cliente toma el primero cuando solo tiene espacio para una etiqueta.
Músculo Secundario (Secondary Muscle)
Músculo sinergista o estabilizador en un ejercicio. Aporta al movimiento sin ser el motor principal (por ejemplo, el tríceps en el press de banca).
Entrenamiento
Sistema de Medición (Measurement System)
Preferencia del usuario sobre el sistema de unidades a usar por defecto en la app. Dos valores posibles: métrico (kg, cm, km) e imperial (lb, ft/in, mi). Se define durante el onboarding y es editable desde el perfil. Este valor decide la unidad por defecto al loggear sets y al registrar medidas corporales, pero la unidad de cada set es editable individualmente porque en el gimnasio es común mezclar equipo en kg y en lb.
Sesión de Entrenamiento (Workout Session)
Periodo durante el cual el usuario realiza ejercicios y registra sus sets. Tiene un inicio y un fin; mientras no tiene fin, la sesión está activa. Al finalizar, el usuario puede asignar un esfuerzo percibido (1-10) que describe qué tan exigente fue la sesión completa.
La sesión vive en el teléfono: se crea, se edita y se cierra offline, y llega al servidor por Sync (ver más abajo). Ver Sesiones de Entrenamiento para el ciclo de vida completo.
Al consultar el historial, cada ejercicio de una sesión muestra su nombre de catálogo vigente (si el equipo renombra un ejercicio, todo el historial refleja el nuevo nombre); el identificador histórico estable es el exercise_code, un snapshot tomado al loggear. Un ejercicio archivado sigue visible en el historial, marcado como archivado.
Set
Una serie individual de un ejercicio dentro de una sesión, registrada con peso, repeticiones, tiempo y/o distancia, según el Tipo de Medición de Set del ejercicio. Lleva su propio Tipo de Set (calentamiento, trabajo, drop set, hasta el fallo) y opcionalmente RPE, descanso post-set y notas.
Cada set guarda lo que el usuario escribió — valor + unidad — y el sistema deriva un valor canónico en kilogramos para comparar y agregar: registrar en libras o en kilogramos no cambia la detección de récords ni la forma de una gráfica.
Esfuerzo Percibido (Perceived Effort)
Escala 1-10 que el usuario asigna a la sesión completa al finalizarla; refleja qué tan exigente fue el entrenamiento en su totalidad. No confundir con RPE, que se aplica por set.
RPE (Rate of Perceived Exertion)
Escala 1-10 por set indicando qué tan cerca de fallo muscular llegó el usuario en esa serie (10 = fallo completo, 9 = pude hacer una más, etc.). Es opcional y se ingresa al loggear cada set.
Superset
Agrupación de 2 a 10 ejercicios que el usuario realiza en secuencia sin descanso entre ellos. Se modela con un identificador compartido entre los ejercicios involucrados, no por contigüidad posicional: el usuario puede crear o deshacer supersets en cualquier momento, e incluso reordenar ejercicios sin perder la membresía del superset.
Rutina (Routine)
Plantilla de entrenamiento reutilizable. Una rutina define una lista ordenada de ejercicios, y cada ejercicio prescribe sus sets con valores objetivo: repeticiones, peso, tipo de set, etc. El usuario crea rutinas para no tener que reconstruir el mismo entrenamiento cada vez que va al gimnasio.
Al iniciar una sesión desde una rutina, el teléfono precarga los ejercicios y sets con los valores objetivo. El usuario puede modificar los valores durante el entrenamiento sin afectar la rutina original.
Las rutinas pueden ser de usuario (creadas por él) o editoriales (provistas por Bodibly, visibles para todos). Una rutina puede existir sin pertenecer a ninguna carpeta.
Guardar Rutina desde una Publicación (Save Routine)
Un usuario puede guardar como propia la rutina que otro compartió en una publicación. Si la rutina usa ejercicios custom del autor, esos ejercicios se copian a la cuenta de quien guarda — la copia es suya, y un cambio del autor no la afecta. Todo ocurre como una sola operación: no puede quedar una rutina apuntando a ejercicios que no se importaron, ni ejercicios importados sin su rutina.
Carpeta de Rutinas (Routine Folder)
Agrupación organizativa de rutinas. Una carpeta contiene una o más rutinas en un orden definido por el usuario. Las carpetas no tienen lógica de negocio — no hay fechas, horarios ni progresión automática. Son puramente organizacionales.
Ejemplo de uso: un usuario crea la carpeta "Jacked & Tan 2.0" y dentro coloca 6 rutinas, una por día de entrenamiento. Para entrenar, abre la carpeta, elige la rutina del día actual, y comienza la sesión. El criterio de qué rutina hacer hoy es del usuario.
Una rutina puede pertenecer a varias carpetas simultáneamente o a ninguna.
Relación con Programas (futuro): cuando el sistema implemente programas (mesociclos con progresión), las carpetas servirán como base sobre la cual se añadirá lógica de programación semanal. Hoy son solo contenedores.
Récord Personal (Personal Record / PR)
Mejor marca histórica del usuario en un ejercicio para una métrica concreta. Cinco tipos de récord: 1RM estimado (fórmula de Epley), peso máximo en una serie, mejor volumen de serie (peso × reps), mejor tiempo y mayor distancia.
Los récords se derivan de las sesiones: cuando una sesión finalizada llega al servidor por sync, el sistema compara sus mejores marcas contra el histórico e inserta los récords nuevos. La sesión es la fuente de verdad y los récords pueden reconstruirse; la derivación es idempotente, así que reprocesar una sesión no duplica récords. Los sets de calentamiento no compiten.
Analítica de Ejercicio (Exercise Stats)
Vista derivada de los datos crudos del entrenamiento: las mejores marcas all-time del usuario en un ejercicio, más una serie temporal con un punto por sesión finalizada donde el ejercicio aparece. Sirve la pantalla de detalle del ejercicio (charts de progresión). No introduce datos propios — es una proyección de récords y sets.
Historial de Ejercicio (Exercise History)
Listado set-por-set de las sesiones donde el usuario hizo un ejercicio, de la más reciente a la más antigua. Complementa la analítica: stats agrega para charts, history es el ledger crudo. Si un ejercicio aparece dos veces en una sesión (bloque de técnica + bloque de trabajo), cada aparición es un bloque independiente con sus propios sets.
Sync y offline-first
Sync
El mecanismo por el que los datos del usuario viajan entre el teléfono y el servidor. Bodibly es offline-first: el teléfono es la fuente de verdad de los datos del usuario (sesiones, rutinas, carpetas, ejercicios custom, medidas) y puede operar sin conexión indefinidamente. Cuando hay red, la app empuja sus cambios y trae los del servidor; el catálogo viaja en el mismo canal, en dirección servidor → teléfono.
Consecuencias de dominio, no detalles técnicos:
- Los borrados de datos de usuario son lógicos (soft delete): un borrado físico sería invisible para un dispositivo que estaba offline, que resucitaría el dato en su próximo push.
- Todo dato del usuario tiene un solo dueño: el servidor no arbitra conflictos entre dispositivos más allá de "gana el último en escribir".
- Existe una cuota absoluta por cuenta (filas y bytes empujados) que protege el servicio de una cuenta desbocada; una cuenta llena siempre puede borrar.
El contrato técnico completo vive en docs/OFFLINE_FIRST.md del repo del servidor.
Social
Ver Red Social para el diseño completo.
Cuenta Privada (Private Account)
Ajuste del usuario que decide quién puede ver su contenido: una cuenta pública es visible para cualquier usuario autenticado; una privada, solo para sus seguidores aprobados. La privacidad vive en la cuenta, no en cada publicación — es el modelo Instagram, no el modelo Facebook. El perfil básico (username, nombre, bio, contadores) es visible siempre, porque una cuenta que nadie puede encontrar no puede recibir solicitudes.
Seguir (Follow)
Relación unidireccional entre dos usuarios: si A sigue a B, A ve las publicaciones de B en su feed. B puede seguir a A sin que A lo siga. Cuando ambos se siguen es un seguimiento mutuo — no se usa el término "amigos".
Seguir a una cuenta pública es inmediato. Seguir a una privada crea una Solicitud de Seguimiento.
Solicitud de Seguimiento (Follow Request)
Petición pendiente de seguir a una cuenta privada. El dueño la acepta o la rechaza; mientras está pendiente, el solicitante no ve nada. Una solicitud pendiente es una acción por resolver, no historial: permanece visible en las notificaciones del dueño sin importar su antigüedad, hasta que la responda.
Bloqueo (Block)
Relación dura entre dos usuarios: bloquear a alguien corta el vínculo en ambas direcciones — deja de verte, dejas de verlo, y los follows existentes entre ambos se deshacen. El bloqueado no es notificado.
Publicación (Post)
Contenido social que un usuario comparte. Una publicación lleva una imagen, un entrenamiento, o ambos — nunca ninguno — más un texto corto opcional (max 280 caracteres):
- Imagen — foto del entrenamiento, equipo o lo que el usuario quiera compartir. Pasa por un pipeline de procesamiento (re-encode, corrección de orientación, reducción de tamaño) que además elimina todos los metadatos, GPS incluido.
- Entrenamiento — referencia a una sesión finalizada, de la que se muestran los números de resumen (duración, volumen, ejercicios). Con
share_details, el autor comparte además el detalle (ejercicios y sets); sin él, los datos crudos siguen siendo privados. - Si la publicación compartió una rutina, otros pueden guardarla (ver Save Routine).
La audiencia la decide la privacidad de la cuenta del autor, no la publicación. Para sacar una publicación del perfil sin borrarla existe el archivo: una publicación archivada solo la ve su autor, y puede restaurarse.
Kudo
Reconocimiento de un usuario a una publicación — el "like" de Bodibly, con vocabulario propio del dominio fitness (como en Strava). Un kudo por usuario por publicación; se puede retirar. El autor recibe una notificación agrupada ("A X, Y y 3 más les gustó tu publicación"). No hay comentarios.
Feed (Home Feed)
Lista cronológica (más reciente primero) de publicaciones de usuarios a los que sigues. No hay algoritmo, no hay contenido sugerido, no hay posts patrocinados. Si no hay publicaciones visibles, la app muestra un empty state con el descubrimiento de atletas.
Descubrimiento (Discovery)
Búsqueda de personas por nombre o username. Las cuentas privadas sí aparecen en los resultados — una cuenta que nadie puede encontrar no puede recibir solicitudes de seguimiento — pero su contenido sigue cerrado hasta que aprueben al seguidor. No hay pipeline de recomendación: el descubrimiento es búsqueda explícita, por diseño.
Notificación (Notification)
Aviso al usuario de que algo pasó con su contenido o su cuenta: kudos recibidos (agrupados por publicación), nuevos seguidores, solicitudes de seguimiento. El inbox muestra los últimos 90 días — una notificación no leída más vieja deja de contar por sí sola — con una excepción: las solicitudes de seguimiento pendientes no caducan, porque son acciones por resolver y no historial.
Avatar
Foto de perfil del usuario. Es la única imagen de perfil; pasa por el mismo pipeline de procesamiento que las imágenes de publicaciones. Reemplazarla destruye la anterior.
Moderación
Reporte (Report)
Denuncia de un usuario sobre una publicación o una cuenta. Alimenta la cola de moderación del panel de staff, donde un moderador lo revisa y decide: sin acción, sanción o ban.
Sanción (Sanction)
Cierre de una funcionalidad concreta de una cuenta — publicar, dar kudos o seguir — mientras todo lo demás sigue funcionando. Puede ser temporal o permanente, y expira sola. Las sanciones son un historial: levantar una no la borra, porque el reincidente es exactamente lo que un moderador necesita ver.
Regla de diseño: una sanción solo cierra verbos que crean — una cuenta sancionada de publicar sigue pudiendo editar, archivar, borrar y dejar de seguir. Reducir el grafo o limpiar lo propio nunca se bloquea.
Vocabulario: el panel etiqueta la sanción de publicar como "Silenciar (mute)", pero la API y el dominio hablan solo de sanciones y features — la palabra "mute" queda reservada para un futuro mute usuario-a-usuario, que es otra cosa.
Ban
Cierre total de la cuenta: la sanción máxima. Un usuario baneado no puede iniciar sesión ni renovar la que tiene. Puede ser temporal o permanente, y expira solo. "Eliminar un usuario" no existe — el entrenamiento, las rutinas y las publicaciones lo referencian — así que el ban es lo que significa quitar a alguien de la plataforma. Levantar un ban restaura la cuenta intacta.
Takedown de Imagen
Retiro de una imagen del almacenamiento y del CDN — "nadie más puede descargar esto". Lo que no puede hacer: borrar la copia que un teléfono ya descargó. Las imágenes de publicaciones además se sirven con URLs firmadas que expiran, así que un link filtrado muere solo.
Panel de administración
Staff
Usuario de Bodibly con un rol en el panel de administración. Ser staff es una condición separada de la cuenta: se otorga y se quita sin tocar los datos de usuario.
Rol de Staff (Staff Role)
Conjunto de permisos con un rango jerárquico. Dos reglas cargan todo el modelo: jerarquía — nadie puede actuar sobre un par o un superior, ni sobre sí mismo — y contención — nadie puede otorgar un permiso que no tiene. El superadmin es el rango máximo y solo se crea por operación directa en el servidor, nunca por API.
Permiso (Permission)
Capacidad concreta del panel: gestionar el catálogo, banear usuarios, sancionar, gestionar roles, etc. El catálogo de permisos vive en código — igual que el catálogo de medidas corporales — así que agregar uno no requiere migración.
Cuentas y acceso
Registro y OTP
El registro verifica el email con un código de un solo uso (OTP) enviado por correo. Un email solo puede pertenecer a una cuenta.
Google Sign-In
Inicio de sesión federado. La identidad se ancla al subject de Google, nunca al email: los emails cambian de dueño, la cuenta de Google no. Un email verificado por Google que coincide con una cuenta existente se vincula a ella en lugar de crear una segunda — seguro solo porque ambos lados probaron esa dirección. Apple está previsto y no vinculará por email (Hide My Email reparte direcciones relay que no coinciden con nada, a propósito).
Medidas corporales
Los términos de antropometría — Antropometría, Medida Corporal, Tipo de Medida, Perímetro, Pliegue Cutáneo, Protocolo de Pliegues, Método de % de Grasa — están definidos en Medidas Corporales, junto con las decisiones de diseño que los sostienen (lateralización, ISAK, por qué el servidor guarda milímetros y no conclusiones).
Relación entre recursos
- Un Ejercicio pertenece a un Patrón de Movimiento y a un Tipo de Medición de Set, sugiere un Equipo principal y acepta alternativos, involucra uno o más Músculos con rol (primario o secundario) y se clasifica bajo una o más Disciplinas.
- Los Músculos siempre pertenecen a un Grupo Muscular.
- Una Sesión de Entrenamiento contiene Ejercicios posicionados (opcionalmente en Supersets), cada uno con sus Sets. Solo puede haber una sesión activa por usuario.
- Una Rutina prescribe ejercicios y sets objetivo; una Carpeta agrupa rutinas sin lógica propia.
- Un Récord Personal se deriva de los sets de una sesión finalizada.
- Un Usuario puede seguir a otros; a una Cuenta Privada solo tras una Solicitud de Seguimiento aceptada. Un Bloqueo corta la relación en ambas direcciones.
- Una Publicación lleva imagen y/o referencia a una sesión; su audiencia la decide la privacidad de la cuenta del autor. Recibe Kudos, que generan Notificaciones.
- Un Reporte puede terminar en una Sanción (cierra una feature) o un Ban (cierra la cuenta).
- Las Medidas Corporales son un eje de progreso independiente: nada las relaciona con sesiones, ejercicios ni publicaciones, y son siempre privadas.
Notas
- Las definiciones pueden evolucionar a medida que la app crece.
- Si tienes dudas sobre un término, consulta este glosario antes de nombrar variables, endpoints o pantallas.
¿Falta algún término? ¡Sugiere una definición nueva!