Skip to content

For Developers

This section is for people building, modifying, or shipping Phytograph itself — not end users of the desktop app. If you're trying to use Phytograph to analyze a plant scan, you want the User Guide.

What's here

  • Getting started — clone, install Python/Node deps, build the PyInstaller backend, run a dev instance.

  • Architecture — three processes (renderer, main, Python sidecar), the narrow IPC bridge, the version-lock contract.

  • Development — dev loop, building local installers, releasing via tag, the non-negotiable E2E testing rules.

  • Backend API — HTTP endpoints served by backend-api/main.py and a generated Python reference.

  • Troubleshooting — common build, sidecar, and dev-loop failures and their root causes.

Quick orientation

Three processes, three boundaries:

  • Renderer (React, no Node) talks to the backend over HTTP and to the OS via a narrow IPC bridge.
  • Main (Electron) supervises the Python sidecar and exposes a handful of OS surfaces (dialogs, fs, persistent store).
  • Backend (FastAPI, bundled by PyInstaller) does all heavy compute on 127.0.0.1:<backend-port>, a port chosen dynamically per app instance.

The supervisor enforces a three-way version lock between backend-api/main.py (BACKEND_VERSION), src/shared/constants.ts (EXPECTED_BACKEND_VERSION), and package.json (version). See Version Lock.