236 lines
5.2 KiB
Markdown
236 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```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.
|