Hydro Builder is a browser-based 3D builder for laying out pumps, reservoirs, pipe runs, fittings, towers, trays, and return lines with live water-flow feedback.

It is built for fast iteration:

click-to-place parts
drag to reshape runs
snap connectors pipe-to-pipe
switch between builder, x-ray, water, and 3D views
inspect pump output, head, open ends, and system health while you build

What this repo contains

frontend: React + TypeScript + Vite app in the repo root
backend: lightweight Express API in server/index.js with SQLite persistence
simulation: in-browser flow and diagnostics for pumps, restrictions, head, loops, and open drains

Linux quick start

These instructions assume Ubuntu or Debian first. Equivalent packages work on Arch, Fedora, or other distros.

1. Install system dependencies

sudo apt update
sudo apt install -y git curl build-essential python3 make g++

2. Install Node.js 20

Use Node 20 LTS. The app is Vite-based and that is the sane floor here.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

You want Node 20.x or newer.

3. Clone and enter the project

git clone https://gitea.thetempleofdoom.com/drjones/hydro-builder-app.git
cd hydro-builder-app

4. Install JavaScript dependencies

npm install

5. Create your local env file

cp .env.example .env

Minimum local env:

PORT=3000
JWT_SECRET=change-this-for-real-use
STRIPE_SECRET_KEY=sk_test_replace_me

Notes:

PORT is for the backend API server.
JWT_SECRET should be changed for any non-throwaway environment.
STRIPE_SECRET_KEY is only needed if you are testing billing or checkout flows.

How to run it

You have three useful ways to start the app.

Frontend only

Use this when you are working on the builder UI, 3D scene, layout, snapping, or water visualization.

npm run dev

Open:

http://localhost:5173

Backend only

Use this when you are debugging auth, saved projects, payments, or SQLite behavior.

npm run server

API runs on:

http://localhost:3000

SQLite database file:

server/database.sqlite

Frontend and backend together

This is the normal local setup.

npm run dev:all

That starts:

Vite frontend on 5173
Express backend on 3000

Build commands

npm run typecheck
npm run build
npm run preview

What they do:

typecheck: TypeScript validation only
build: production build into dist/
preview: serve the production build locally

Builder workflow

This app is only useful if the editing loop is fast. The current interaction model is:

Place and connect

click a part in the left library, then place it in the scene
drag a part near another connector to snap
green connectors mean joined
amber connectors mean open

Manipulate runs

drag a body or gizmo to move a selected part
double-click plumbing to grab the full run
selected pipes expose stretch handles
drag connector dots to snap endpoints
use front or side views for vertical edits

Tune flow

select a pump
adjust rated flow and max head in the inspector
switch to Water mode to isolate active flow behavior
use Flow to animate movement through the system

Diagnose problems

The bottom diagnostics area will surface issues like:

disconnected pump inlet
open drain / leaking end
dead-end branch
head too high for the selected pump
closed or restrictive path
loop or return behavior

Project structure

.
├── src/                  # React app, store, simulation, 3D scene, UI
├── server/               # Express API + SQLite bootstrap
├── docs/                 # screenshots and design notes
├── dist/                 # production build output
├── package.json
└── README.md

Important files:

src/App.tsx: top-level app shell
src/components/SceneCanvas.tsx: 3D scene and camera behavior
src/components/PartMesh.tsx: part rendering and direct manipulation
src/store/builderStore.ts: state, selection, undo/redo
src/simulation/flowSimulator.ts: flow graph and pump logic
src/parts/catalog.ts: part definitions and connector metadata

Troubleshooting on Linux

`npm install` fails building native modules

Make sure these exist:

sudo apt install -y build-essential python3 make g++

Port 5173 or 3000 is already in use

Find and kill the process:

lsof -i :5173
lsof -i :3000
kill -9 <pid>

Backend starts but auth or save features fail

Check:

.env exists
JWT_SECRET is set
server/database.sqlite is writable

Water or 3D rendering looks broken