SEE EVERY DROP
TAKE FULL CONTROL

SMART WATER APP STUDENT GUIDE

Guide 01 | Set up | Clone | Run | Develop with AI

Use this guide to run Smart Drops on your computer, keep a working Git copy, and make your first change in an IDE. The supplied app uses Node.js and Vite with HTML, CSS and JavaScript. Its building model, simulated data, graphics and guides are included.

1. Prepare your computer

• Install Node.js 22.12 or newer from https://nodejs.org/. npm is included. Restart your editor after installation.
• Install Git from https://git-scm.com/downloads and an editor such as Visual Studio Code from https://code.visualstudio.com/ or Cursor. Keep the project in a permanent local folder, for example C:\EDU\SmartWaterApp.
• Use GitHub Copilot, Codex or another coding assistant if available to you. An AI account or plan may be required for those tools; the water app itself has no sign-in requirement.

Starter repository: https://github.com/smart-water-EDU/SmartWaterApp. Viewing or cloning a public repository does not require a GitHub account. Pushing work requires permission or your own repository.

2. Clone and open the project

Option A - Use your editor

In VS Code, press Ctrl+Shift+P and choose Git: Clone. Paste the HTTPS repository address below, choose the parent folder and select Open when cloning finishes. In Cursor, use its clone/open-project workflow for the same repository.

https://github.com/smart-water-EDU/SmartWaterApp.git

Option B - Use a terminal

Open Git Bash or a terminal in your chosen parent folder and run:

git clone https://github.com/smart-water-EDU/SmartWaterApp.git

cd SmartWaterApp

Open this folder in your IDE. It must contain package.json and index.html. Clone once; reopen the same folder for later sessions. Your local folder may have a different name, such as smart-water-app.

3. Install once and start locally

Open Terminal > New Terminal inside the project. Check the tools, install dependencies and start Vite:

node --version

npm --version

npm install

npm run dev

Open http://127.0.0.1:5173/ if the browser does not open automatically. This is an address on your own computer. Keep the Vite terminal running; save an edited file to see the change. Ctrl+C in that terminal stops Vite. Restart with npm run dev next time; install again only when dependencies change.

Do not double-click index.html to run this version. Node runs the development tools; index.html remains the browser entry point. Internet is needed for installation, Git/AI services and the optional weather API. The supplied simulation and saved designs use local data.

4. Choose your AI development environment

• VS Code with Copilot: enable AI features or open Chat, sign in if requested, and give the assistant access to this project. Use the editor's Source Control view to inspect every changed file.
• Cursor: open the same local folder and use its AI chat/agent. Run npm commands in the project terminal. Review the proposed changes before keeping them.
• Codex: open or select the local project in the Codex app or a supported IDE integration. Start by asking it to explain a file; review its changes and tests before continuing. See the official setup link at the end.
• Lovable is a separate browser-based workflow. Its Upload code workflow can import a repository ZIP into a new project; Git sync then creates a new repository. It does not attach to this existing repository through Git sync. Keep the local starter copy and agree the import/submission route with your teacher before using it.

5. Explore and make your first change

Start with Monitoring, Management, Maintenance and Development. Change the simulation clock, select a floor/module, inspect sensor gauges, and open Development > Additional Systems. The heat and rainwater designers already work; red STUDENTS EXTENSIONS panels identify places for new ideas.

Create a local branch before editing:

git switch -c student/my-idea

Begin with a small styling change, then use Guide 02 for an engineering extension. Suggested prompts:

READ ONLY: Read README.md and explain src/app.js, src/components/, src/styles/ and data/. Identify the STUDENT EXTENSION markers. Do not modify files.

FIRST EDIT: Make the selected tab slightly clearer. Change only the relevant CSS. Preserve the layout, data and calculations. Explain the selectors changed and how I can check the result.

Review the diff, try the feature, then run the checks in a second project terminal while Vite stays open:

npm test

npm run build

The build creates dist/ for deployment. Source changes belong in src/, index.html, data/ or docs/, not in dist/ or node_modules/. Build/start validate the water inputs and regenerate derived sensors; they do not intentionally regenerate the supplied consumption baseline.

6. Find the right files and save your work

• src/app.js connects tabs and controls. src/components/ holds the designers, charts and network interaction. src/styles/ holds appearance; the building SVG is embedded in index.html.
• src/heat-recovery-model.js, src/rainwater-model.js and src/pump-model.js separate engineering calculations from their interfaces. tests/ contains focused checks.
• data/ holds building/profile JSON, separate cold/hot module CSVs and all sensor channels for 8,760 hours of 2026. Run npm run data:build after intentional source CSV edits. npm run data:generate deliberately replaces the supplied water baseline; do not use it for a proposed design.
• Designs and scenarios are saved in your browser for this origin. Git saves source files; it does not automatically include browser-only designs. Keep the same address/browser and document or export scenario inputs for submission.

Use git status and git diff to review changes. Commit selected files with a clear message. Keep work on your own branch/fork or the teacher's assigned repository; do not push to the shared main branch without permission. Before updating from the starter repository, commit or back up your work and follow the teacher's merge instructions. Ask for help with conflicts; avoid force-push or broad file deletion.

7. Common problems and official help

• npm cannot find package.json: the terminal is in the wrong folder. Open the folder containing package.json, then start a terminal there.
• The local address will not open: check that npm run dev is still running. Port 5173 in use means another copy may already be running; inspect that terminal before closing it.
• PowerShell blocks npm.ps1: use npm.cmd install and npm.cmd run dev, or choose the Git Bash terminal profile. An old Node version requires upgrading Node and reopening the terminal.

Vite: https://vite.dev/guide/ | Copilot: https://code.visualstudio.com/docs/setup/copilot/ | Codex: https://learn.chatgpt.com/docs/ide | Lovable Git workflow: https://docs.lovable.dev/integrations/github

DEVELOP SMART WATER SOLUTIONS

Guide 02 | Student extensions | Engineering models | Test and improve

Use the working Smart Drops application to develop and test a building-scale water-management idea. Start with a small sewage heat-recovery improvement, extend rainwater collection next, and then tackle a control, efficiency or resilience feature. AI can help write code; your group must explain the assumptions, units and results.

1. Follow a repeatable development workflow

Complete Guide 01 first. Run npm run dev from your local SmartWaterApp folder and create a Git branch for your work. The four tabs are Monitoring, Management, Maintenance and Development. The symbolic building, meters and 2026 water data are educational assumptions, not actual Kremmergården measurements.

• Explore the chosen tool before coding. Read README.md and its model note in docs/. Search for STUDENT EXTENSION in the source and STUDENTS EXTENSIONS in the interface. Identify what works already and what your idea adds.
• Define a small operator task, inputs with units, assumptions, outputs, a comparison case and a few expected results. Sketch the interaction before asking AI to implement it.
• Keep calculations in a model module, controls in its component, styles in its scoped CSS and checks in tests/. Reuse the shared hourly data. Store proposed designs separately from the baseline.
• Ask AI for one bounded change. Review the diff, run npm test and npm run build, and try the tool in the browser. Test normal, zero and failure conditions. Save a Git checkpoint after a working step.
• Ask another student to complete the task without help. Record at least two specific observations, improve the feature and repeat the same task. Explain any trade-off that remains.

FIRST PROMPT: Inspect the existing [tool] and its STUDENT EXTENSION marker. Explain its current inputs, outputs and calculation files. Propose one small improvement and three checks. Do not edit files yet.

2. Start simple with sewage heat recovery

Open Development > Additional Systems > Sewage Heat Recovery, or enable Sanitary drainage and select the exchanger symbol. Choose an exchanger, add heat consumers and set wire allocations to 100%. Move or rename nodes and save a local design. Try water preheating, ventilation, space heating and thermal storage to understand what each allocation means.

Understand the existing calculations

The selected-hour heater gauge estimates electrical input in kW and the sewage gauge shows temperature in degrees C. The two energy gauges sum hourly values from January 1 through the selected simulation hour: baseline heater electricity and recovered thermal heat, both in kWh. kW is power; kWh is energy. Temperature is an instantaneous hourly reading, not a yearly sum.

Available thermal kW = sewage L/min / 60 x 4.186 x max(0, sewage deg C - cold deg C)

Heater electric kWh per hour = useful heater thermal kWh / 0.98

Recovered kWh per hour = min(40% of heater electric kWh, available heat x effectiveness, exchanger limit)

The 40% figure is a teaching target, not a measured saving. Available sewage heat and equipment capacity can reduce it; the supplied full-year example is about 39%. Different selections or weather/water-load scenarios can give less. Recovery is zero without a placed exchanger and a connected heat consumer. Only the water-preheating allocation directly reduces the estimated water-heater electricity input. Other heat uses need their own demand models.

Your first development task

Add one editable engineering assumption, such as the 40% recovery target or a fouling factor, and show its effect on the existing year-to-date energy result. Connect it to the existing designer and local save. Keep the window within the viewport and preserve the selected module, baseline meters and other tabs.

• Work in src/heat-recovery-model.js and src/components/heat-recovery-designer.js. Presets are in data/heat_recovery_presets.json; styles and persistence have their own heat-recovery files. Read docs/HEAT-RECOVERY-DESIGNER.md.
• Check zero sewage flow, no positive temperature difference, no exchanger/consumer and a low heater demand. Recovered heat cannot exceed the available heat or the configured limit. Saving and reopening must retain the new assumption.

IMPLEMENTATION PROMPT: Add an editable recovery target to the existing sewage heat-recovery designer and saved design. Reuse heatEnergySummary, cap recovery by available sewage heat, keep kW and kWh distinct, and add zero-flow and year-to-date tests. Preserve unrelated files and baseline CSVs.

Next steps: add hourly consumer heat-demand limits, auxiliary pumping energy, fouling/cleaning, temperature feasibility and thermal storage. Keep sewage and clean-water circuits separate in the conceptual design. Saving this preview does not apply savings to Monitoring automatically; any future link must use a separate scenario.

3. Extend rainwater collection and reuse

Open Development > Additional Systems > Rainwater Collector. The roof frame, connected consumer cards and weather panel already work. Edit roof area, runoff, collection efficiency, storage and pumping capacity. Select irrigation, flush tanks, cooling or parking washing. Inspect the hourly weather and monthly precipitation graphs, then save and reopen the design.

Use Import CSV for a complete hourly 2026 file or Get API data for Open-Meteo historical reanalysis. Earlier complete years are clearly replayed on the 2026 timeline; they are not actual 2026 building weather. API access needs internet; supplied/imported rows and saved designs remain local. Reset returns to the supplied synthetic weather.

Collected litres = precipitation mm x roof area m2 x runoff x collection efficiency

Previous storage + inflow = supplied rainwater + overflow + end storage

Mains backup = consumer demand - supplied rainwater

Your first rainwater extension can add a configurable first-flush loss or a demand schedule for one consumer. Keep the existing hourly balance and shared dataset. Show how a wet spell and a dry spell change useful supply, overflow and mains backup. Add explicit treatment/quality assumptions for non-potable purposes; the model does not yet simulate snow storage or melt.

• Work in src/rainwater-model.js, src/components/rainwater-designer.js and data/rainwater_presets.json. Weather inputs are in data/rainwater_weather_2026.csv; API code is separate in src/weather-api.js. Read docs/RAINWATER-DESIGNER.md.
• Test zero rainfall, an empty/full tank, zero pump capacity, high demand and missing imported values. Storage must stay within capacity and every hour must conserve water. API failure must retain the previous weather data.

IMPLEMENTATION PROMPT: Extend the existing rainwater model with an editable first-flush loss. Preserve its hourly storage balance, weather import and local saving. Compare wet/dry periods and add checks for zero rain and overflow. Do not replace the existing designer or baseline water dataset.

4. Develop the tagged student extension panels

After the two guided examples, choose the extension assigned by your teacher. The red STUDENTS EXTENSIONS tags mark UI starting points. Management contains Smart Pump Control, Extreme Conditions Management and Water Saving. Development contains Energy Efficiency, Additional Systems and Retrofit / Proposals. The designer source also includes searchable STUDENT EXTENSION comments.

Smart Pump Control

Start with a transparent pressure or operating-schedule rule. Inputs include hourly demand, required head, efficiency and capacity. Compare it with the supplied pump-energy model in src/pump-model.js. Report energy in kWh, peak kW and unmet demand/pressure. Changing a control label alone cannot create savings; the simulated operating conditions must change. More advanced studies may compare regression, neural networks, predictive control or reinforcement learning after validating the simple rule.

Water Saving and Energy Efficiency

For Water Saving, model one fixture, leakage-reduction or demand-schedule intervention against a reference demand. For Energy Efficiency, compare pressure optimization, hot-water setpoints or the heat-recovery preview with comfort and operating limits. Report assumptions, water/energy saved and any service shortfall. Reuse src/data-model.js, src/scenarios.js and the pump/heat models rather than multiplying independent meters by unrelated random factors.

Extreme Conditions Management and Maintenance

Simulate two cases such as pump failure and peak demand, or a supply outage and intense rain. Use event severity, duration, supply capacity and storage; show affected loads, unmet demand and a reasoned response. Maintenance already includes leak investigations and pump-energy degradation examples. Extend detection or uncertainty in an isolated model; an alarm should explain the threshold crossed. All controls remain simulated.

5. Use retrofit scenarios to challenge your solution

In Development > Retrofit / Proposals > Open Building Editor, select a whole module, choose a new tenant type, adjust area/occupancy/schedule or import hourly cold/hot loads. Apply a local scenario and inspect its effects on floors, meters, demand and pump energy. The supplied baseline remains separate. Restore supplied baseline in the editor to compare with the starter model.

Use the changed demand to test your extension. Does pump control serve a new restaurant? Is rainwater storage sufficient for its flushing demand? Does wastewater heat availability change? Use the existing retrofit engine as a scenario tool; extending it is optional unless assigned. Its files and CSV rules are described in docs/DATA-SCHEMA.md.

6. Validate and hand in a reproducible result

• Provide the working source and a short README explaining how to run the feature. Include changed source/presets, dependencies and relevant inputs; exclude node_modules/ and generated dist/. Browser-only designs need an export or a documented set of inputs.
• Explain the operator problem, inputs, units, assumptions and calculation/control rule. Distinguish thermal energy, electrical energy, flow, volume and temperature. State which results are simulated.
• Compare at least two meaningful scenarios and include at least three checks: a normal case, a limiting/zero case and a failure or missing-data case. Record npm test and npm run build outcomes and confirm other tabs, meters and local saving still work.
• Include two peer-testing observations, the changes you made and evidence of improvement. Submit through the teacher's assigned branch/repository/folder route, not the shared starter main branch.

REVIEW PROMPT: Review only my student extension. Check units, hourly/annual balances, zero and failure inputs, local persistence and baseline isolation. Show any defect with a small reproducible example. Explain the engineering result so our group can defend it.