NutriFlow — conductor/ Contexto del Proyecto

📦 product.md · tech-stack.md

🥗 product.md conductor/product.md

NutriFlow

SaaS B2B para clinicas de nutricion: planes alimentarios personalizados generados por IA.

Problema y solucion

Los dietistas dedican 2-4h/semana por paciente elaborando planes manualmente. NutriFlow automatiza la generacion con IA usando el perfil clinico del paciente, reduciendo ese tiempo a 15 minutos.

Usuarios objetivo

Clinicas de nutricion (5-20 dietistas) Dietistas independientes Coaches de salud

Features

Feature	Estado	Descripcion
Generador de planes IA	in-progress	GPT-4o genera menu semanal personalizado
Perfil clinico paciente	implementado	CRUD de pacientes con datos clinicos
Lista de compra auto	planificado	Genera lista de la compra desde el menu
Seguimiento progreso	planificado	Dashboard de adherencia y metricas
Portal del paciente	planificado	App web para que el paciente vea su plan

KPIs objetivo

Tiempo generacion plan ≤ 15 min vs 3h manual

Clinicas activas (mes 6) 50 objetivo seed

NPS clinicas > 45 medicion trimestral

⚙️ tech-stack.md conductor/tech-stack.md

Lenguajes y Frameworks

Python 3.12 Backend API principal backend

FastAPI 0.111 Framework REST + async backend

React 18.x UI frontend del dietista frontend

TypeScript 5.x Tipado estatico frontend frontend

Base de datos e IA

PostgreSQL 16 Base de datos principal datos

pgvector 0.7.x Embeddings perfiles nutricionales datos

OpenAI API gpt-4o Generacion planes alimentarios IA

Infraestructura y testing

Docker latest Contenedores dev + prod infra

Railway — Deploy produccion PaaS infra

pytest 8.x Tests Python (cobertura ≥ 80%) QA

Ruff + ESLint latest Linting Python + TypeScript QA

🔁 workflow.md · product-guidelines.md

🔄 workflow.md conductor/workflow.md

Metodologia: TDD + Trunk-Based

Leer artefactos de contexto

Antes de cualquier sesion: leer index.md → tracks.md → plan del track activo.

Spec + Plan

Definir spec.md con criterios de aceptacion. Desglosar en tareas atomicas en plan.md.

Implementar con tests primero

TDD: escribir test → hacer pasar → refactorizar. Cobertura minima 80%.

Commit y PR

Formato: feat(plan-gen): add dietary restrictions filter. PR requiere 1 aprobacion + checks verdes.

Actualizar contexto

Al completar un track: actualizar product.md y tracks.md. Commit junto al codigo.

Quality Gates

🧪 Tests 100% pass · coverage ≥ 80% obligatorio

🔍 Linting Ruff + ESLint: cero errores obligatorio

👁️ Code Review Min. 1 aprobacion en PR obligatorio

🔷 Tipos mypy (Python) + tsc (TS): sin errores obligatorio

Convenciones Git

Branch: feature/<track-id>-descripcion

Commit: type(scope): mensaje en imperativo

Tipos: feat fix chore docs refactor

🎨 product-guidelines.md conductor/product-guidelines.md

Voz y Tono

Profesional y cercano: el dietista es experto, hablale como colega

Directo: maximo 2 frases por mensaje de estado

Clinico donde importa, lenguaje llano por defecto

Sin jerga de startup ("synergize", "leverage") — solo espanol claro

Terminologia Canonica

✓ plan alimentario dieta (connotacion negativa)

✓ paciente usuario / cliente (contexto clinico)

✓ clinica workspace / cuenta (dominio B2B)

✓ perfil clinico datos / formulario (precision medica)

✓ generar plan crear / calcular (accion IA)

Formato de Mensajes de Error

[Componente] Que ocurrio. Que hacer a continuacion.

[PlanIA] No se pudo generar el plan: perfil incompleto. Completa las alergias alimentarias antes de continuar.

[Auth] Sesion expirada. Inicia sesion de nuevo para continuar.

Convenciones de Copy UI

CTAs en imperativo: "Generar plan", "Ver seguimiento", "Anadir paciente"

Estados vacios con accion sugerida, nunca solo "Sin datos"

Confirmaciones destructivas en rojo con verbo explicito: "Eliminar plan permanentemente"

Fechas en formato DD/MM/AAAA (estandar clinico espanol)

🚦 tracks.md

📋 tracks.md — Registro de Work Units conductor/tracks.md

Tracks Activos

NF-TRACK-003

Motor de generacion de planes IA con restricciones dieteticas

conductor/tracks/NF-003/ · tipo: feature · ▲ prioridad alta

@carlos

Asignado

in-progress

NF-TRACK-004

Endpoint exportacion PDF del plan semanal

conductor/tracks/NF-004/ · tipo: feature · ▲ prioridad alta

@laura

Asignado

en revision

NF-TRACK-005

Lista de compra automatica desde el menu semanal

conductor/tracks/NF-005/ · tipo: feature · ● prioridad media

@carlos

Asignado

planificado

NF-TRACK-006

Dashboard de adherencia y seguimiento del paciente

conductor/tracks/NF-006/ · tipo: feature · ● prioridad media

@laura

Asignado

planificado

Tracks Completados

NF-TRACK-001

Configuracion inicial del proyecto (FastAPI + React + PostgreSQL + Docker)

Completado: 2026-05-20

completado

NF-TRACK-002

CRUD de pacientes con perfil clinico (alergias, patologias, IMC)

Completado: 2026-06-05

completado

🔮 Continuidad entre Sesiones de IA

Al iniciar una sesion

Leer conductor/index.md para orientarse

Revisar tracks.md para ver el trabajo activo

Leer tracks/NF-00X/plan.md del track en curso

Verificar que los artefactos de contexto esten actualizados

Al terminar una sesion

Actualizar plan.md con el progreso actual

Marcar tareas interrumpidas con [~] y nota del punto de parada

Commit del trabajo en progreso a la rama feature

Actualizar tracks.md si el estado cambio

🗂️ Estructura del directorio · Checklist de validacion

📁 Estructura conductor/

conductor/

index.md — hub de navegacion

product.md — vision, features, KPIs

product-guidelines.md — tono, terminologia

tech-stack.md — stack, deps, infra

workflow.md — metodologia, QA

tracks.md — registro work units

code_styleguides/

python.md

typescript.md

tracks/

NF-003/

spec.md

plan.md

metadata.json

NF-004/

spec.md

plan.md

NF-005/

NF-006/

✅ Checklist de Validacion de Contexto

Ejecutar antes de cada track

✅ product.md refleja la vision actual del producto
✅ Usuarios objetivo descritos con precision
✅ Lista de features actualizada con estados correctos
✅ tech-stack.md lista todas las dependencias actuales con versiones
✅ Infraestructura y targets de deploy correctos (Railway, Docker)
✅ workflow.md describe las practicas actuales del equipo
✅ Quality gates definidos y conocidos por todo el equipo
⬜ tracks.md muestra todo el trabajo activo sin tracks abandonados
⬜ Dependencias entre tracks NF-003 y NF-005 documentadas
⬜ Styleguide Python actualizado con patrones de la API OpenAI

Anti-patrones a evitar

✗ Contexto obsoleto: actualizar al cerrar cada track, no solo al inicio
✗ Contexto disperso: no crear nuevos tipos de documentos fuera de conductor/
✗ Contexto implicito: si se menciona algo repetidamente, anadir al artefacto
✗ Hoarding: las actualizaciones de contexto se revisan en PR como el codigo

Contexto como Artefacto de Primera Clase