Skip to content

ronalc90/meal-prep

BranchesTags

Repository files navigation

MealPrep

Planificador de comidas semanal con lista de compras automatica

Node.js Express Prisma React Vite TypeScript License MIT

Sobre el Proyecto

MealPrep es una aplicacion web full-stack para planificar comidas semanales y generar listas de compras automaticas. Permite a los usuarios crear recetas con ingredientes detallados, organizar un plan de comidas semanal con desayuno, almuerzo, cena y snacks, y luego generar una lista de compras inteligente que agrega cantidades, convierte unidades y agrupa los items por pasillo del supermercado.

Problema que resuelve

Planificar comidas para la semana y hacer la lista de compras manualmente es tedioso y propenso a errores: se olvidan ingredientes, se compran duplicados y se pierde tiempo en el supermercado. MealPrep automatiza todo este proceso.

Caracteristicas

  • Gestion de recetas: Crear, editar, eliminar y buscar recetas con ingredientes, tiempos de preparacion y calorias
  • Planificacion semanal: Calendario interactivo para asignar recetas a cada dia y tipo de comida (desayuno, almuerzo, cena, snack)
  • Auto-generacion de comidas: Rellenar automaticamente el plan semanal basado en preferencias y calorias
  • Lista de compras inteligente: Generacion automatica con agregacion de ingredientes, conversion de unidades y agrupacion por categoria
  • Exportar lista de compras: Formato texto plano listo para compartir o imprimir
  • Dashboard: Estadisticas semanales con calorias, progreso de compras y recetas populares
  • Autenticacion JWT: Registro, login y rutas protegidas
  • Busqueda y filtrado: Por titulo, tiempo de preparacion y calorias
  • Paginacion: Listado de recetas con paginacion configurable
  • Validacion: Esquemas Zod para todas las entradas del API

Arquitectura

MealPrep es un monorepo con dos aplicaciones independientes:

04-MealPrep/
├── backend/          # API REST con Express + Prisma + SQLite
├── frontend/         # SPA con React + Vite + TailwindCSS
└── docs/             # Documentacion del proyecto

Backend

API REST en Express con arquitectura en capas: Routes -> Services -> Prisma (Repository). Cada ruta delega la logica de negocio al servicio correspondiente. Validacion de entrada con Zod, autenticacion con JWT y manejo centralizado de errores.

Frontend

Single Page Application en React 18 con React Router v6. Estado global gestionado con Context API (AuthContext + MealPlanContext). Comunicacion con el backend via un cliente API centralizado con interceptores de autenticacion. Estilos con TailwindCSS.

Documentacion detallada de la arquitectura en docs/ARCHITECTURE.md

Stack Tecnologico

Capa Tecnologia
Runtime Node.js 18+
Backend Framework Express 4.x
ORM Prisma 5.x
Base de Datos SQLite (desarrollo) / PostgreSQL (produccion)
Validacion Zod 3.x
Autenticacion JWT (jsonwebtoken)
Hashing bcryptjs
Frontend Framework React 18
Bundler Vite 6.x
Estilos TailwindCSS 3.x
Routing React Router 6.x
Lenguaje TypeScript 5.x
Testing Jest + Supertest

Instalacion

Prerrequisitos

  • Node.js >= 18
  • npm >= 9

Backend

cd backend

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus valores

# Generar cliente Prisma y ejecutar migraciones
npx prisma generate
npx prisma migrate dev

# (Opcional) Poblar la base de datos con datos de ejemplo
npm run prisma:seed

# Iniciar en modo desarrollo
npm run dev

El servidor inicia en http://localhost:3004

Frontend

cd frontend

# Instalar dependencias
npm install

# Iniciar en modo desarrollo
npm run dev

La aplicacion inicia en http://localhost:5173 con proxy automatico al backend.

Variables de Entorno

Backend (backend/.env)

Variable Descripcion Ejemplo
DATABASE_URL URL de conexion a la base de datos file:./dev.db
JWT_SECRET Secreto para firmar tokens JWT mi-secreto-seguro
JWT_EXPIRES_IN Tiempo de expiracion del token 7d
PORT Puerto del servidor 3004
NODE_ENV Entorno de ejecucion development
CORS_ORIGIN Origenes permitidos (separados por coma) http://localhost:5173

API Documentation

Base URL: http://localhost:3004/api

Endpoints

Metodo Ruta Descripcion Auth
GET /health Health check del servidor No
POST /auth/register Registrar nuevo usuario No
POST /auth/login Iniciar sesion No
GET /auth/me Obtener perfil del usuario autenticado Si
GET /recipes Listar recetas (publicas + propias) Opcional
GET /recipes/:id Obtener detalle de una receta No
POST /recipes Crear nueva receta Si
PUT /recipes/:id Actualizar receta Si
DELETE /recipes/:id Eliminar receta Si
GET /meal-plans/current Obtener plan de la semana actual Si
GET /meal-plans/week/:weekStart Obtener plan por fecha de inicio Si
POST /meal-plans Crear plan de comidas Si
PUT /meal-plans/:id Actualizar plan de comidas Si
POST /meal-plans/:id/auto-generate Auto-generar comidas sugeridas Si
POST /shopping-lists/generate Generar lista de compras desde plan Si
GET /shopping-lists/:mealPlanId Obtener lista de compras Si
PATCH /shopping-lists/:id/items/:itemId Marcar/desmarcar item Si
GET /shopping-lists/:mealPlanId/export Exportar lista como texto plano Si
GET /dashboard/stats Obtener estadisticas del dashboard Si

Documentacion completa con ejemplos curl en docs/API.md

Algoritmo de Lista de Compras

El corazon de MealPrep es el algoritmo de generacion de listas de compras:

  1. Recoleccion: Recorre todos los items del plan semanal con sus recetas e ingredientes
  2. Escalado: Multiplica las cantidades por el factor de porciones (servings / recipe.servings)
  3. Normalizacion: Convierte todas las unidades a su base comun (ml para volumen, g para peso)
  4. Agregacion: Suma las cantidades del mismo ingrediente
  5. Formato legible: Convierte de unidades base a unidades practicas (g -> kg, ml -> L/cups/tbsp)
  6. Agrupacion: Organiza los items por categoria de supermercado (PRODUCE, DAIRY, MEAT, PANTRY, etc.)

Conversion de Unidades

  • Volumen: tsp, tbsp, cup, fl oz, ml, L -> base en ml
  • Peso: oz, lb, g, kg -> base en g
  • Sin unidad: unit, bunch, slices, stalks -> se mantienen tal cual

Explicacion detallada en docs/SHOPPING-LIST-ALGORITHM.md

Estructura del Proyecto

04-MealPrep/
├── backend/
│   ├── prisma/
│   │   ├── schema.prisma          # Modelo de datos
│   │   └── seed.ts                # Datos de ejemplo (16 recetas)
│   ├── src/
│   │   ├── __tests__/             # Tests unitarios e integracion
│   │   │   ├── auth.test.ts
│   │   │   ├── recipes.test.ts
│   │   │   ├── mealPlans.test.ts
│   │   │   ├── shoppingList.test.ts
│   │   │   ├── dashboard.test.ts
│   │   │   ├── integration.test.ts
│   │   │   ├── setup.ts
│   │   │   └── helpers.ts
│   │   ├── middleware/
│   │   │   ├── auth.ts            # Middleware JWT
│   │   │   ├── errorHandler.ts    # Manejo centralizado de errores
│   │   │   └── validate.ts        # Validacion con Zod
│   │   ├── routes/
│   │   │   ├── authRouter.ts
│   │   │   ├── recipeRouter.ts
│   │   │   ├── mealPlanRouter.ts
│   │   │   ├── shoppingListRouter.ts
│   │   │   └── dashboardRouter.ts
│   │   ├── services/
│   │   │   ├── authService.ts
│   │   │   ├── recipeService.ts
│   │   │   ├── mealPlanService.ts
│   │   │   ├── shoppingListService.ts
│   │   │   └── dashboardService.ts
│   │   ├── types/
│   │   │   └── schemas.ts         # Esquemas Zod + tipos
│   │   ├── utils/
│   │   │   ├── errors.ts          # Jerarquia de errores
│   │   │   ├── jwt.ts             # Utilidades JWT
│   │   │   ├── pagination.ts      # Paginacion generica
│   │   │   ├── prisma.ts          # Cliente Prisma singleton
│   │   │   └── unitConversion.ts  # Conversion de unidades
│   │   ├── app.ts                 # Configuracion Express
│   │   └── index.ts               # Entry point
│   ├── jest.config.ts
│   ├── tsconfig.json
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Navbar.tsx
│   │   │   ├── ProtectedRoute.tsx
│   │   │   ├── RecipeCard.tsx
│   │   │   ├── RecipeForm.tsx
│   │   │   ├── WeeklyCalendar.tsx
│   │   │   └── ShoppingListView.tsx
│   │   ├── context/
│   │   │   ├── AuthContext.tsx     # Estado de autenticacion
│   │   │   └── MealPlanContext.tsx # Estado del plan semanal
│   │   ├── pages/
│   │   │   ├── LoginPage.tsx
│   │   │   ├── RegisterPage.tsx
│   │   │   ├── DashboardPage.tsx
│   │   │   ├── RecipesPage.tsx
│   │   │   ├── RecipeDetailPage.tsx
│   │   │   ├── MealPlannerPage.tsx
│   │   │   └── ShoppingListPage.tsx
│   │   ├── services/
│   │   │   └── api.ts             # Cliente API centralizado
│   │   ├── types/
│   │   │   └── index.ts           # Interfaces TypeScript
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── index.css
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   └── package.json
├── docs/                          # Documentacion
├── .github/workflows/ci.yml       # CI/CD
└── README.md

Decisiones Tecnicas

Decision Justificacion
Express sobre Fastify Ecosistema maduro, mayor cantidad de middleware disponible y familiaridad del equipo
Prisma sobre TypeORM Type-safety nativo, migraciones declarativas, cliente generado con autocompletado
Vite sobre CRA Build significativamente mas rapido, HMR instantaneo, configuracion minima
Monorepo sin herramientas Simplicidad para un MVP; cada app tiene su propio package.json sin necesidad de Turborepo/Nx
SQLite en desarrollo Zero-config, portable; cambia a PostgreSQL en produccion via Prisma
Context API sobre Redux Estado predecible sin boilerplate para una aplicacion de esta escala
Zod sobre Joi Inferencia de tipos TypeScript nativa, menor bundle size

Decisiones detalladas con contexto completo en docs/DECISIONS.md

Testing

cd backend

# Ejecutar todos los tests
npm test

# Ejecutar tests en modo watch
npm run test:watch

# Ejecutar tests con cobertura
npx jest --coverage

Cobertura de Tests

  • Autenticacion (registro, login, perfil)
  • CRUD completo de recetas
  • Planes de comida (crear, actualizar, auto-generar)
  • Listas de compras (generar, toggle items, exportar)
  • Dashboard (estadisticas)
  • Integracion end-to-end

Despliegue

Backend (Railway)

# El backend se despliega directamente desde el directorio backend/
# Railway detecta Node.js automaticamente
# Configurar variables de entorno en el dashboard de Railway

Frontend (Vercel)

cd frontend
npm run build
# El directorio dist/ se despliega en Vercel

Guia completa de despliegue en docs/DEPLOYMENT.md

Roadmap

  • Soporte para multiples idiomas (i18n)
  • Modo offline con Service Workers
  • Compartir planes de comida entre usuarios
  • Integracion con APIs de nutricion para datos mas precisos
  • Notificaciones push para recordatorios de compras
  • Escanear codigos de barras para marcar items comprados
  • Presupuesto semanal con tracking de gastos
  • Exportar lista de compras a formato PDF
  • App movil con React Native

Licencia

Distribuido bajo la Licencia MIT. Ver LICENSE para mas informacion.

Autor

Desarrollado por Ronald.

GitHub: @ronalc90

About

Planificador de comidas semanal con lista de compras automatica - Express + React

ronalc90.github.io/meal-prep/

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages