User Guide

Audience

Anyone running or operating the Race Day Dashboard on the hosting Windows machine -- setting up the login for the first time, starting/stopping the server day to day, and using the dashboard itself. No coding required for normal use; node/command-line steps are only needed for first-time login setup or troubleshooting.

Prerequisites

• Node.js installed and on PATH (run.bat checks for it and stops with a link to nodejs.org if missing).
• The shared MongoDB config file already in place at C:\Users\Dinesh\projects-config\db.json (same file/format used by other QDG tools against the same database) -- this guide assumes it already exists; it is not created by this project.
• npm dependencies (express, express-session, bcryptjs, mongodb, exceljs, pdfkit) -- run.bat installs these automatically on first run if node_modules is missing or incomplete.

First-time login setup

The dashboard has one shared username/password (not per-user accounts). Set it up once before the first run:

1. Open Command Prompt in the project folder.
2. Run:

   node setup-auth.js
   

3. Choose a username, then a password (minimum 6 characters, typed hidden). Confirm the password when asked.
4. This writes the username and a securely-hashed password to C:\Users\Dinesh\projects-config\auth.json (outside the project folder, never committed to git). The plaintext password itself is never written anywhere or sent over the network.

To change the username/password later, rerun node setup-auth.js -- it will ask to confirm overwriting the existing login -- then restart the server for the change to take effect.

Running the dashboard

1. Double-click run.bat in the project folder.
   • Installs/updates npm dependencies automatically if needed.
   • Starts server.js in its own console window titled "Race Day Dashboard Server".
   • Waits a few seconds, then opens http://localhost:3000/ in Chrome (or your default browser if Chrome isn't found).
2. Log in with the username/password from the setup step above.
3. To stop the server, close the "Race Day Dashboard Server" console window.

(Advanced/alternative: run node server.js directly from a terminal instead of run.bat -- useful if you want to see server logs inline, or need to set environment variables such as PORT, DB_CONFIG_PATH, AUTH_CONFIG_PATH, or DB_CONNECTION_NAME for that run.)

Using the dashboard

• Date: use Prev day / Next day, or pick a date directly. Include trials toggles whether trial meetings are shown.
• Discipline tabs: switch between Thoroughbred, Harness, and Greyhound -- each has its own meeting grid.
• Filters: search meeting by name (matches the start of the name), Country, TAB/Non-TAB meetings, Issue type (missing/duplicate jockey, missing TAB, missing trainer, schedule issue, or meetings with/without any issue), and Race status (Upcoming/Running/Completed/Abandoned/ Resulted -- applied per race, since one meeting can have races at different statuses at once).
• Race detail: click any race's time cell to open a popup with every runner's tab number, horse, jockey, trainer, finishing position (once resulted), and issue.
• Reports: "Download report" (top of page) exports every issue across the whole date; the small download icon next to a meeting name exports that one meeting's full race/runner detail. Both offer CSV, Excel, JSON, and PDF.
• Theme: the sun/moon button top-right toggles Light/Dark mode; your choice (and your filter selections) are remembered on that browser via localStorage.
• Auto-refresh: the page reloads itself every 3 minutes to pick up new data (paused while a race-detail popup is open); a countdown next to the date shows time remaining.
• Logout: click "Logout" next to your username, top-right.

Troubleshooting

• run.bat says "No dashboard login is set up yet" -- run node setup-auth.js once (see First-time login setup above), then run run.bat again.
• Login page says "Login is not set up on this server yet" -- same cause/fix as above; AUTH_CONFIG_PATH is missing or unreadable.
• Login page says "Incorrect username or password" -- re-check what you typed; if forgotten, rerun node setup-auth.js to set a new one (choosing "yes" to overwrite).
• Dashboard fails to load / shows a DB error -- check that the file at DB_CONFIG_PATH (default C:\Users\Dinesh\projects-config\db.json) exists and contains a valid MDB_MCP_CONNECTION_STRING for whichever entry matches DB_CONNECTION_NAME (default mongodb-prod).
• Port already in use -- set the PORT environment variable to a free port before starting the server (e.g. set PORT=3001 before run.bat, or edit the variable at the top of run.bat).
• run.bat can't find Node.js -- install it from nodejs.org and ensure it's on PATH, then try again.

Verification

• http://localhost:3000/health returns a DB connectivity check without needing to log in.
• After logging in, the dashboard grid loads for today's date with all three discipline tabs showing a meeting count.
• Filters narrow the grid as expected, clicking a race time opens the runner-detail popup, and a report download (CSV/Excel/JSON/PDF) completes successfully.