Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JaiderT/CoffeePrice/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running the full CoffePrice stack on your local machine. You will have the Express backend listening on port 8081 and the React frontend on port 5173 in under ten minutes. The ML pipeline runs separately on GitHub Actions and is not required to explore most platform features locally.

​
Prerequisites

Make sure the following are available on your machine before you begin:
RequirementMinimum versionNotes
Node.js18 LTSBackend and frontend both require Node 18+
npm9+Bundled with Node 18
MongoDB6+A local instance or a free MongoDB Atlas cluster
nodemonanyInstalled automatically as a dev dependency
Python3.9+Only needed if you want to run the ML pipeline locally

​
Setup Steps

1

Clone the repository

git clone https://github.com/JaiderT/CoffeePrice.git
cd CoffeePrice
2

Install backend dependencies

cd backend
npm install
This installs Express 5, Mongoose, Passport, node-cron, Nodemailer, the OpenAI SDK, and all other backend dependencies listed in backend/package.json.
3

Configure the backend environment

Copy the example file and fill in your values:
cp .env.example .env
The table below documents every variable in backend/.env.example:
VariableRequiredDescription
MONGODB_URI✅Full MongoDB connection string, e.g. mongodb://localhost:27017/coffeeprice or an Atlas SRV URI
JWT_SECRET✅Secret used to sign and verify JWT tokens. Use a long random string
SESSION_SECRET✅Secret for Express session (used by Passport during OAuth flow)
FRONTEND_URL✅Origin the CORS policy allows. Set to http://localhost:5173 locally
JWT_EXPIRES_IN✅JWT lifetime, e.g. 1d
NODE_ENV✅development locally, production on Railway
GOOGLE_CLIENT_IDOAuthGoogle OAuth 2.0 client ID from Google Cloud Console
GOOGLE_CLIENT_SECRETOAuthGoogle OAuth 2.0 client secret
GOOGLE_CALLBACK_URLOAuthDefaults to http://localhost:8081/api/auth/google/callback
EMAIL_USERAlertsGmail (or SMTP) address used by Nodemailer to send price alerts
EMAIL_PASSAlertsApp password for the email account above
OPENAI_API_KEYChatbotOpenAI API key for the /api/chatbot route
NEWSAPI_KEYNewsAPI key for newsapi.org
GNEWS_API_KEYNewsAPI key for gnews.io
THENEWSAPI_TOKENNewsToken for thenewsapi.com
NOTICIAS_GENERAR_AL_INICIARNewstrue to seed news immediately on server start. Default: false
NOTICIAS_POR_CICLONewsArticles fetched per cron cycle. Default: 3
NOTICIAS_DIAS_CONSERVARNewsDays to keep articles before expiry
NOTICIAS_MAX_HORAS_FUENTENewsMaximum age (hours) of source articles to accept. Default: 12
NOTICIAS_MIN_ARTICULOS_FUENTENewsMinimum articles accepted from a single source per run. Default: 1
NOTICIAS_MAX_ARTICULOS_FUENTENewsMaximum articles accepted from a single source per run. Default: 12
NOTICIAS_OBJETIVO_CANDIDATASNewsTarget number of candidate articles per cycle. Default: 8
NOTICIAS_HORAS_REVISAR_DUPLICADOSNewsLook-back window (hours) for duplicate detection. Default: 48
NOTICIAS_MAX_HORAS_SIN_ACTUALIZARNewsHours before the news cron forces a refresh. Default: 8
NOTICIAS_MIN_ACTIVASNewsMinimum active articles to keep in the feed. Default: 6
NOTICIAS_HORAS_INVENTARIONewsInventory window (hours) for article accounting. Default: 72
NOTICIAS_MODO_ADAPTACIONNewsAdaptation strategy (local or cloud). Default: local
NOTICIAS_BLOQUEAR_REPETIDAS_HORASNewsHours to block a repeated article from re-appearing. Default: 168
NOTICIAS_MIN_INTERVALO_REVISION_MSNewsMinimum milliseconds between news review cycles. Default: 300000 (5 min)
A minimal .env for local development looks like this:
MONGODB_URI=mongodb://localhost:27017/coffeeprice
JWT_SECRET=change_me_to_a_long_random_string
SESSION_SECRET=another_random_secret
FRONTEND_URL=http://localhost:5173
JWT_EXPIRES_IN=1d
NODE_ENV=development
4

Start the backend

npm run dev
nodemon watches for file changes and restarts automatically. You should see:
Servidor corriendo en http://localhost:8081
Noticias automaticas: activas
The server waits for MongoDB to be reachable before binding to the port (via esperarMongoDisponible).
5

Install frontend dependencies

Open a new terminal tab, then:
cd frontend
npm install
This installs React 19, Vite 5, Tailwind CSS 4, react-router-dom 7, Recharts, Mapbox GL, and all other frontend packages.
6

Configure the frontend environment

Create frontend/.env (Vite reads .env files in the frontend/ directory):
cp .env.example .env   # if an example exists, otherwise create manually

VITE_API_URL=http://localhost:8081
VITE_MAPBOX_TOKEN=your_mapbox_public_token
VITE_MAPTILER_KEY=your_maptiler_key
VariableDescription
VITE_API_URLFull base URL of the backend. All Axios requests are prefixed with this value
VITE_MAPBOX_TOKENPublic Mapbox access token for the buyer map. Get one free at mapbox.com
VITE_MAPTILER_KEYMapTiler API key used as an alternative tile source. Get one at maptiler.com
The buyer map (/features/buyer-map) will not render without valid map tokens, but all other platform features work without them.
7

Start the frontend

npm run dev
Vite starts the dev server with HMR enabled:
VITE v5.4.x  ready in XXX ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
Open http://localhost:5173 in your browser. The React app talks to the Express backend at http://localhost:8081.

​
Health Check

Once the backend is running, verify it is healthy and MongoDB is connected: 
curl http://localhost:8081/healthz
Expected response when the database is connected: 
{
  "status": "ok",
  "service": "backend",
  "db": "connected"
}
If MongoDB is not yet reachable the backend responds with HTTP 503 and "status": "degraded". All /api/* routes also return 503 until the database connection is established — this is by design to prevent partial reads during startup. You can also hit the root endpoint for a quick API map: 
curl http://localhost:8081/

{
  "status": "ok",
  "message": "Backend CoffePrice activo",
  "api": "/api",
  "available": [
    "/api/auth/login",
    "/api/auth/register",
    "/api/auth/me",
    "/api/noticias",
    "/api/precios",
    "/api/predicciones"
  ]
}
ML pipeline is not required locally. The Prophet + XGBoost prediction pipeline runs automatically via GitHub Actions (Monday–Friday at 20:15 UTC). It commits updated prediction artefacts to backend/datos/ and ml-service-experimental/datos/, which the backend serves through /api/predicciones. If you want stale-but-functional predictions locally, those committed artefacts are already in the repository. To run the pipeline yourself, install dependencies from ml-service-experimental/requirements_hibrido.txt using Python 3.11 and execute python ml-service-experimental/actualizar_todo.py.

Build docs developers (and LLMs) love

Get started for freeTalk to us