Desktop Installation

The Masterplan Optimiser desktop application is the main tool for building, optimising, and managing your event schedule. It runs locally on your computer and does not require a server or internet connection for core functionality. The installer bundles everything the application needs - there is no need to install Python, Node.js, or any other dependencies separately.

System Requirements

Step 1 - Download the Application

Head to the Downloads page and grab the installer for your operating system:

Step 2a - Install on Windows

1. Run the downloaded .exe installer. Windows may show a SmartScreen warning because the application is not code-signed. Click More info then Run anyway.
2. Follow the installer prompts and choose an install location.
3. Once installed, launch Masterplan Optimiser from the Start Menu or desktop shortcut.
4. On the first launch, the application will set up its backend services automatically. This may take a moment.

Step 2b - Install on macOS

1. Open the downloaded .dmg file.
2. Drag Masterplan Optimiser into your Applications folder.
3. On first launch, macOS Gatekeeper may block the app. Open System Settings → Privacy & Security and click Open Anyway.
4. If the app shows a message saying it is damaged, clear the quarantine flag by running the following command in Terminal:

   xattr -cr /Applications/Masterplan\ Optimiser.app

5. If prompted, allow terminal access so that the application can start its backend services.

Step 2c - Install on Linux

1. Make the AppImage executable:

   chmod +x Masterplan-Optimiser-*.AppImage

2. Run it directly:

   ./Masterplan-Optimiser-*.AppImage

3. No installation step is needed - AppImage is portable.

Alternative - Running from Source

If you prefer to run from source (or no installer is available for your platform), you can clone and set up the project manually. This requires Python 3.11+, Node.js 18+, and Git.

1. Clone the repository

git clone https://github.com/Brian-Funk/masterplanOptimiserV3---App-Public.git
cd masterplanOptimiserV3---App-Public

2. Set up Python environments

The backend includes the optimisation engine. Set up a single Python virtual environment:

cd backend
python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate  # macOS / Linux
pip install -r requirements.txt
pip install -r ../compute/requirements.txt
deactivate

3. Install frontend dependencies

cd ../web
npm install

4. Configure the environment

cd ../backend
cp .env.desktop .env    # Unix
copy .env.desktop .env  # Windows

5. Launch the application

# Windows (starts all services + Electron window)
start-desktop.bat

# macOS / Linux
./start-desktop.sh

The launch script starts the backend (port 8000 by default) and the frontend (port 3000 by default) inside an Electron window. Development and automated validation may select other distinct HTTP loopback ports. You can also run in browser mode with start.bat / start.sh and open http://localhost:3000.

Architecture Overview

The desktop application runs two local services inside an Electron shell:

Desktop Runtime Safeguards

• Packaged releases verify a signed manifest for the complete application, backend and frontend runtime before starting local services. A failed check stops the application.
• The backend requires a fresh per-launch Desktop token. The renderer receives only the exact loopback API URL selected by the shell.
• Explicit backend and frontend URL overrides must be distinct HTTP loopback origins without credentials, paths, queries or fragments.
• On shutdown, the shell stops only the child process trees it owns. It does not close unrelated Electron applications.

Troubleshooting

xattr -cr /Applications/Masterplan\ Optimiser.app

Next Steps

• First Launch - create your first event and explore the dashboard
• Quick Start Guide - a 10-step walkthrough from setup to publishing
• Google Calendar Integration - publish events directly to Google Calendar
• MP Backend Integration - connect the desktop app to the web server