# 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

![Hydro Builder UI](docs/hydro-builder-ui.png)

## 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

```bash
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.

```bash
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

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

### 4. Install JavaScript dependencies

```bash
npm install
```

### 5. Create your local env file

```bash
cp .env.example .env
```

Minimum local env:

```dotenv
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.

```bash
npm run dev
```

Open:

- [http://localhost:5173](http://localhost:5173)

### Backend only

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

```bash
npm run server
```

API runs on:

- [http://localhost:3000](http://localhost:3000)

SQLite database file:

- `server/database.sqlite`

### Frontend and backend together

This is the normal local setup.

```bash
npm run dev:all
```

That starts:

- Vite frontend on `5173`
- Express backend on `3000`

## Build commands

```bash
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

```text
.
├── 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:

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

### Port 5173 or 3000 is already in use

Find and kill the process:

```bash
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.