TIP-IT

Plataforma de propinas digitales. Los trabajadores reciben propinas vía QR único o búsqueda por username; los clientes pagan con tarjeta a través de Stripe Connect.

Stack

• Frontend: React 18 + Vite + Tailwind CSS + PWA (vite-plugin-pwa)
• Backend: Node.js + Express.js
• Base de datos: MongoDB (Mongoose)
• Pagos: Stripe (PaymentIntents + Connect Express)
• Auth: JWT (24h) + bcrypt

Estructura

tip-it/
├── backend/            API REST (Express + MongoDB + Stripe)
│   └── src/
│       ├── config/      conexión a Mongo, cliente de Stripe
│       ├── models/      User, Worker, Transaction
│       ├── middleware/  auth (JWT), rate limiting, validación, errores
│       ├── controllers/ lógica de negocio por dominio
│       └── routes/      definición de endpoints
└── frontend/           PWA React (mobile-first)
    └── src/
        ├── pages/        landing, auth, worker, client, historial, perfil
        ├── components/   nav, tarjetas, rating, rutas protegidas
        ├── context/      AuthContext (sesión JWT)
        └── services/     cliente axios

Requisitos previos

• Node.js 18+
• MongoDB (local o Atlas)
• Cuenta de Stripe (modo test) con Connect habilitado

Configuración

MongoDB local (sin Homebrew ni sudo)

El proyecto incluye un mongod real (v8.2.6) en backend/.mongo/bin que guarda sus datos en backend/.mongo/data — no requiere Homebrew ni permisos de administrador.

cd backend
npm run mongo:start   # arranca MongoDB en localhost:27017
npm run mongo:status  # verifica que está corriendo
npm run mongo:stop    # lo detiene

MONGO_URI=mongodb://localhost:27017/tip-it en .env ya apunta a este Mongo local. Si prefieres MongoDB Atlas, simplemente reemplaza MONGO_URI por tu cadena de conexión.

Backend

cd backend
cp .env.example .env   # completa con tus valores reales
npm install
npm run mongo:start     # levanta MongoDB local (una sola vez por sesión de trabajo)
npm run dev              # http://localhost:5050 (ver nota de macOS abajo)

Variables de entorno (backend/.env):

Variable	Descripción
PORT	Puerto del servidor API (default 5000)
CLIENT_URL	URL del frontend, usada por CORS y para construir los links del QR
MONGO_URI	Cadena de conexión a MongoDB
JWT_SECRET	Secreto para firmar tokens JWT
JWT_EXPIRES_IN	Expiración del token (default 24h)
STRIPE_SECRET_KEY	Clave secreta de Stripe
STRIPE_WEBHOOK_SECRET	Secreto del endpoint de webhooks de Stripe
STRIPE_CONNECT_REFRESH_URL / STRIPE_CONNECT_RETURN_URL	URLs de retorno del onboarding de Stripe Connect
PLATFORM_FEE_PERCENT	Comisión de TIP-IT sobre cada propina (4–6 recomendado)

macOS: el puerto 5000 suele estar ocupado por AirPlay Receiver (Control Center). Por eso backend/.env y frontend/.env en esta máquina ya están configurados con PORT=5050 / VITE_API_URL=http://localhost:5050/api. Si npm run dev falla con EADDRINUSE en otra máquina, cambia PORT (y VITE_API_URL) a un puerto libre, o desactiva AirPlay Receiver en Preferencias del Sistema → General → AirDrop y Handoff.

Frontend

cd frontend
cp .env.example .env    # completa con tus valores reales
npm install
npm run dev              # http://localhost:5173

Variables de entorno (frontend/.env):

Variable	Descripción
VITE_API_URL	URL base de la API (http://localhost:5000/api en desarrollo)
VITE_STRIPE_PUBLISHABLE_KEY	Clave publicable de Stripe

Crear tu cuenta de Stripe (modo test)

1. Regístrate gratis en dashboard.stripe.com/register.
2. Verifica que el toggle "Test mode" (arriba a la derecha del dashboard) esté activado — así no se procesan cobros reales.
3. Ve a Developers → API keys y copia:
   • Publishable key (pk_test_...) → frontend/.env → VITE_STRIPE_PUBLISHABLE_KEY
   • Secret key (sk_test_...) → backend/.env → STRIPE_SECRET_KEY
4. Ve a Connect → Get started y activa Connect (en modo test se habilita al instante, sin revisión). Esto es lo que permite crear cuentas Express para los trabajadores.

Webhooks de Stripe en desarrollo

El proyecto incluye el Stripe CLI en backend/.stripe-cli (descargado directo del release oficial, sin Homebrew) y ya está autenticado con tu STRIPE_SECRET_KEY — no hace falta stripe login.

cd backend
npm run stripe:listen   # reenvía eventos de Stripe a localhost:5050/api/webhooks/stripe

Déjalo corriendo en una terminal aparte mientras trabajas (junto con npm run dev y npm run mongo:start). El whsec_... que imprime ya está guardado en STRIPE_WEBHOOK_SECRET dentro de backend/.env; si alguna vez cambia, actualízalo ahí.

Para probar que el webhook funciona sin hacer un pago completo:

./.stripe-cli/stripe trigger payment_intent.succeeded --api-key "$(grep STRIPE_SECRET_KEY .env | cut -d= -f2)"

Deberías ver 200 OK tanto en la terminal del listener como en los logs del backend.

Arranque diario (3 terminales)

Ya está todo configurado en esta máquina. Para trabajar necesitas 3 terminales:

# Terminal 1
cd backend && npm run mongo:start && npm run dev

# Terminal 2
cd backend && npm run stripe:listen

# Terminal 3
cd frontend && npm run dev

Luego abre http://localhost:5173. Cuentas de prueba ya creadas:

• Trabajadora: [email protected] / password123 (@ana_barber, Stripe Connect activo)
• Cliente: [email protected] / password123

This is the beginning of the README. Read the rest at the original. Read the full README ↗