hydro-builder-app/README.md

Hydro Builder

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

Check:

• browser console errors
• WebGL is enabled in the browser
• you are on a current Chrome, Chromium, or Firefox build

Current reality

This is not CFD and it is not a full hydraulic solver. It is a fast builder with approximate flow behavior intended to make pipe-to-pipe editing, pump sizing, and obvious routing mistakes easy to see.

That is the right tradeoff for this app right now.