Gridmen

Gridmen is a desktop + web GIS-style grid editing and visualization workspace. It combines an Electron shell, a React/Vite renderer, and a Python (FastAPI) backend.

Repository Layout

High-level structure (monorepo):

.
├─ package.json                # Workspace orchestration (concurrently)
├─ client/                     # Electron desktop shell
│  ├─ package.json             # Electron dependencies + build script
│  ├─ electron/                # Electron main/preload process (TypeScript)
│  └─ src/                     # Renderer app (Vite + React)
│     ├─ package.json          # Frontend dependencies
│     ├─ vite.config.ts        # Dev server + proxy + build output
│     └─ src/                  # React app source (components/core/store/views/...)
├─ server/                     # Python backend project (uv + FastAPI)
│  ├─ pyproject.toml           # Python deps/constraints (incl. GIS stack)
│  ├─ main.py                  # Uvicorn entrypoint
│  └─ py-noodle/               # Local editable dependency used by backend
├─ src/                        # Backend source package (gridmen_backend)
├─ templates/                  # Frontend build output target (generated)
├─ resource/                   # Example datasets / resources
└─ temp/                       # Runtime/temp artifacts

Main Tech Stack (with versions)

Versions are taken from manifests in this repository (e.g. package.json, pyproject.toml).

For full dependency lists, see client/package.json, client/src/package.json, and server/pyproject.toml.

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• Python (3.12 or higher)
• uv (Python package manager) - Install uv

Installation

1. Frontend Dependencies

Install Electron dependencies:

cd ./client
npm install

Install renderer (React/Vite) dependencies:

cd ./client/src
npm install

2. Environment Configuration

Create a .env file in client/src/ with the following content:

# Replace with your local API URL, e.g., http://localhost:8000
VITE_LOCAL_API_URL=http://localhost:8000

# Replace with your remote API URL, e.g., http://xxx.yyy.zzz.www:8000
VITE_REMOTE_API_URL=http://localhost:8000

# Replace with your Mapbox token, e.g., pk.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VITE_MAP_TOKEN=your_mapbox_token_here

Note: Get your Mapbox token from Mapbox Account

3. Backend Dependencies

Navigate to the server directory and install Python dependencies:

cd server
uv run main.py

This will automatically:

• Create a virtual environment in .venv/
• Install all dependencies listed in pyproject.toml
• Start the FastAPI server on http://localhost:8000

Running the Application

From the repository root:

npm start

This command will concurrently:

• Start Electron desktop shell (client/)
• Launch Vite dev server (client/src/) on http://127.0.0.1:5173
• Run the FastAPI backend (server/) on http://localhost:8000

Individual Development Servers

If you prefer to run components separately:

Frontend only (Vite dev server):

cd ./client/src
npm run dev

Electron desktop only:

cd ./client
npm start

Backend only:

cd ./server
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv run main.py

Notes

• The Vite dev server proxies /api and /noodle requests to VITE_LOCAL_API_URL
• Frontend build output is configured to go to templates/
• Press F12 in the Electron app to toggle DevTools