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

Requirement	Minimum	Notes
Operating System	Windows 10+, macOS 12+, Linux	64-bit only
RAM	4 GB	8 GB recommended for large events
Disk Space	~500 MB	For the application and its dependencies

Step 1 - Download the Application

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

Platform	Format	Notes
Windows	`.exe` (NSIS installer)	Includes desktop shortcut and Start Menu entry
macOS	`.dmg` disk image	Drag to Applications folder
Linux	`.AppImage`	Portable - no installation step needed

Step 2a - Install on Windows

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

Step 2b - Install on macOS

Open the downloaded .dmg file.
Drag Masterplan Optimiser into your Applications folder.
On first launch, macOS Gatekeeper may block the app. Open System Settings → Privacy & Security and click Open Anyway.
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
```
If prompted, allow terminal access so that the application can start its backend services.

Step 2c - Install on Linux

Make the AppImage executable:

chmod +x Masterplan-Optimiser-*.AppImage

Run it directly:
```
./Masterplan-Optimiser-*.AppImage
```
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.git
cd MasterplanOptimiserV3---App

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) and the frontend (port 3000) inside an Electron window. 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:

Service	Port	Role
Backend (FastAPI)	`8000`	REST API, SQLite database, Google Calendar integration, schedule optimiser (OR-Tools CP-SAT solver)
Frontend (Next.js)	`3000`	User interface loaded inside the Electron window

Electron Shell

Backend (FastAPI)

Port 8000

REST API
SQLite Database
Google Calendar Integration
OR-Tools CP-SAT Solver

Frontend (Next.js)

Port 3000

User Interface
Rendered in Electron Window

HTTP

High-level architecture: Electron shell wrapping two local services.

Troubleshooting

“python is not recognised” / “command not found”

Python is not on your PATH. Reinstall Python and make sure to tick “Add Python to PATH”, or add it manually in your system environment variables.

Port already in use (errno 10048 / EADDRINUSE)

Another process is using port 8000 or 3000. Close any previously running instances of the application, or use Task Manager / Activity Monitor to end the processes on those ports.

macOS: “App is damaged and can't be opened”

macOS blocks applications that are not signed with an Apple Developer certificate. To open the app, run this command in Terminal after installing:

xattr -cr /Applications/Masterplan\ Optimiser.app

Alternatively, right-click the app and choose “Open” instead of double-clicking.

blank white screen on launch

The frontend may still be compiling. Wait 10-15 seconds and refresh (Ctrl+R / Cmd+R). If running from source, check the terminal for errors.

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