Skip to content

feat: V2 interface (Aqua Atelier), first-run setup, branded emails and website - #5

Merged
dlommm merged 38 commits into
mainfrom
feat/v2-ui
Oct 24, 2026
Merged

dlommm merged 38 commits into
mainfrom
feat/v2-ui

Conversation

@dlommm

@dlommm dlommm commented Oct 24, 2026

Copy link
Copy Markdown
Owner

What this changes

A new interface. Every screen is rebuilt in one design, Aqua Atelier, with light and dark modes. The three old themes are gone. Desktop uses a deep-water masthead with group tabs, or a sidebar if you pick it in Admin. Tablets get a menu sheet and phones a bottom bar.

First-run setup replaces APP_PASSWORD.

  • A fresh install has no owner account. Every page goes to /setup, which asks for a one-time code printed in the server log.
  • The wizard creates the owner with a real name, their own username and a password stored only as a hash.
  • It offers two-step sign-in (skipping it shows a warning and a dashboard reminder), then business details, prices, water targets, colours, crew with temporary passwords, and email.
  • Upgrading an existing install: the owner account keeps working with its current password. On first sign-in the owner is asked once to add a name, pick a username and set a new password. After that APP_PASSWORD is never read.
  • Recovery: docker compose exec app python -m app.manage reset-owner [--clear-2fa] prints a one-time reset link.

New features

  • Chemistry targets and bands that the dose engine, water alerts, charts and the visit screen all read. pH dosing now follows target ± band.
  • Company colour palettes with automatic contrast checks. The customer portal and signing pages follow the palette switch.
  • Branded HTML emails, with the plain-text copy kept, and a block email builder for the visit, invoice, reminder and follow-up emails.
  • Three-pane contract editor; the follow-up period for unsigned contracts is now a setting.
  • QuickBooks billing shows the selected draft's review beside the list on desktop.
  • Analytics overview for 3, 6 or 12 months.
  • Owners can hold a route that they set by hand; the balancer leaves it alone.
  • Equipment page; Admin › Logs and About pages; display preferences per device.

Smaller fixes

  • The property form only accepts an assignee who can hold a route.
  • Visit emails say "Serviced by" instead of "Technician".
  • Deactivating a customer records the date.
  • Demo and sample data use a fictional company and invented addresses.

Website. site/ is a one-page project website, deployed to GitHub Pages by .github/workflows/pages.yml. To enable it: Settings → Pages → Source: GitHub Actions. Its dose calculator runs the same rules as app/dosing.py; I compared them on 2,000 random readings and they match. deploy/docker-compose.yml runs the published image.

Checks

  • All 1614 tests pass and ruff is clean.
  • The visual check passes all 91 renders against a seeded instance.
  • The Docker image boots healthy with only SECRET_KEY set and prints the setup code.
  • I reproduced the CI browser job locally (fresh boot, seed_sample_data.py, then visual_check.py) and it passes.

Deploying

Your .env needs only SECRET_KEY and optionally APP_TZ. Leaving APP_PASSWORD in it does no harm. For a fresh install, run docker compose logs app | grep "Setup code" and open the site.

dlommm added 30 commits October 23, 2026 23:59
Replace the three themes (warm-coastal, control-room, fresh-field) with the
single Aqua Atelier theme from the approved V2 design, in light and dark.

- css/v2.css: the design's component stylesheet, ported from the prototype
- css/base.css: Tailwind colour names mapped onto the new tokens, plus the
  pre-V2 component classes kept working on them
- base.html: deep-water masthead with group tabs and a second row for the
  active group's pages; optional sidebar layout (Admin > Appearance,
  desktop only); menu sheet on tablet and phone; phone bottom bar
- app/nav.py: one navigation model with per-route permission visibility
- appearance settings: nav_layout and header_style replace active_theme
- light/dark is a class on <html> set before first paint
- scripts/seed_demo.py: a 22-customer synthetic company for previews
Today opens on the viewer's own route when they hold one (owners
included): a progress track, a lit next-stop card with Navigate and Start
visit, coming up, done today, and the rest of the crew. Whole crew shows
progress per person and every stop grouped by person, with missed stops,
service holds and today's jobs alongside.

The visit is six steps (Arrival, Water, Chemicals, Tasks, Photos and
notes, Finish) in one form: band scales show the target band and say
Low / In range / High while typing, suggestions are separate from what is
added, and the form still posts whole without JavaScript.
Week is a grid of day cards with numbered stops, done ticks and who is on
each stop; opening a stop keeps move (this week or from now on) and
earlier/later. The route sheet is a black-on-white table with blank
reading boxes, for the person whose route it is.
Greets the signed-in owner, shows today's route as a progress ring with
a lane per person (the owner included), a queue of what needs a decision
(QuickBooks drafts, missed and unassigned stops, overdue invoices, water
alerts, unsigned contracts), open jobs / receivables / revenue / alerts,
six months of revenue, and low stock with warranties running out.
The list is a table with avatars, service, pool, rate and balance (for
people who see money), status chips, city and sort filters and an A–Z
rail; on a phone it keeps name and status. The customer page has a
profile header, a facts strip and tabs: overview, pools and equipment
(warranty state per item, contracts per pool), service history with
out-of-band readings flagged, water trends, billing, agreements, photos,
contact log and the portal.
Customer, property and pool forms use grouped cards with label-and-help
rows, switches and one save bar; holds, the property checklist,
maintenance rules and equipment sit below in their own groups with a
separate danger zone. Search covers jobs and invoices for the office.
Water history charts draw the target band in the theme's band colour.
Jobs are a table with status tabs and counts, late and priority pills;
a job shows its checklist, notes and photos beside a details panel with
start, schedule, the amount to collect and times.
Quotes are a table with status chips; a quote's actions (accept,
decline, convert, duplicate) sit in its header. Contracts list beside
their signed and pipeline value, what needs attention and how a contract
moves; the contract page gets the new header and banners.
Both step through months from the header. Money summary shows billable,
service, chemicals and jobs, then one row per customer. Invoices show
billed, collected and outstanding, status chips, and a table whose rows
open a drawer with the PDF, email, mark sent, regenerate, payments and
void (anchored, so it also works without JavaScript).
Receivables open with balances by age as bars. QuickBooks billing gets a
month stepper and Prepare drafts in its header, a connection bar with
Sync now and the setup drawer, a five-stage pipeline (needs review,
exceptions, held, in QuickBooks, sent) that filters the draft list, and
the draft review page shows the five-step progress track.
A segmented range filter with custom dates, a revenue hero with profit,
visits, revenue per visit and the top customer, and the views as tabs.
…tory

The route planner picks a weekday and a person from chips with stop
counts, plots the stops with the current order and the saved order,
compares their travel estimates and redraws as stops move. Balance,
water alerts, operations health and inventory get the new headers,
KPI strips, tables and cards. The demo seed now places properties on a
map.
Settings become the Admin page (design v0.12): Company, Field, People and
access and System groups in a side menu that wraps into chips on tablets
and phones, with crew, the audit log, water testers and operations
linked from it. #section links open a section. Appearance replaces the
retired theme picker with the navigation layout and masthead style.
Sign-in and two-factor pages float a card over the deep-water band;
403/422/error pages use the centred denied layout; the portal gets the
company band header, section chips and cards.
base.html set a top-level `u` for the signed-in person, which shadowed
the crew form's `u` (the person being edited): New crew member opened
pre-filled with the signed-in owner's details. The shell's variables are
now _-prefixed, with a regression test.

Payment reminder emails gave the due date as bare ISO; they now read
"September 30, 2026". scripts/visual_check.py asserts the Aqua Atelier
fonts and colours and the masthead at phone, tablet and desktop widths;
the retired theme-screenshot script is removed.
Account gets Display on this device: light or dark, density, text size
and motion, applied before first paint. Equipment lists every piece on
an active pool with its warranty state, soonest first, with a filter for
warranties ending within 60 days; the dashboard's warranty rows link
there.
Admin › Logs shows the last 2,000 log lines kept in memory (the same
records and format stdout gets, so path redaction still applies), with
level and text filters, an expandable raw line and a download. Admin ›
About shows the running version, runtime, images, licence and the update
steps; the app does not contact anything to check for updates.
…and charts

One setting per reading (target and band) now drives the dose engine's
deadbands, water alerts, the history chart and the visit screen. pH dosing
follows target ± band instead of a fixed 7.2-7.8. Limits reject typos that
would switch dosing off, and an invalid stored pair falls back to defaults.
Admin › Appearance offers six named palettes or a custom colour, each with
a mini preview. Light and dark tokens are derived server-side from one base
colour and solved for contrast (accent text 4.6:1, accent on tint 7:1,
white on masthead and hero 6:1), so any colour stays readable. Lagoon keeps
the hand-tuned tokens. Only a validated hex reaches the page; chart colours
stay fixed. The hero, profile avatar and active masthead tab now follow the
palette instead of hard-coded teal.
/routes/assign now accepts an active owner as well as an active technician, rejecting inactive people and properties with a 400 and unknown ids with a 404. An assigned stop joins the end of the receiving route. The route planner lists owners after technicians, marked "set by hand", and gains a "Move a stop to another route" form (POST /routes/plan/assign) that returns to the planner.

The balancer still balances technicians only: it never moves stops onto or off an owner, and shows each owner holding stops as a read-only "by hand" column. Unassigned stops can be given to anyone, owners included, through a "Someone else" picker. The balance screen moves to the V2 grid with load shading.

The disabled-assignee pill on Today and Week now says "disabled owner" for an owner.
Selecting a draft on /billing opens its review in a right-hand pane
(/billing?ym=..&draft=ID), loaded with HTMX on wide screens and rendered
server-side for reloads and no-JS. Rows stay real links to
/billing/drafts/{id}, which phones and tablets keep using, and the open
row carries aria-current. The review lives in one partial shared by the
full page, the pane fragment and the split view.

Forms in the pane send back=list so actions return to the split view;
the fixed token is the only value honoured. Permissions, CSRF and status
semantics are unchanged.
The analytics page now opens on an overview scoped by one range filter:
a revenue hero with a like-for-like delta over full months only (the
current month is drawn, labelled partial and left out of comparisons)
and a sparkline; visits, revenue per visit and active customers;
revenue by month stacked by service, chemicals and repairs; income mix;
recurring weekly service by route; receivables by age; a rate-review
scatter of chemical cost share against the rate with a 15% line; and
customers gained and lost.

Everything is computed server-side from the models, reusing the existing
revenue rules to the cent. Charts are SVG marks with HTML labels, each
with role=img, an aria-label and a table view; hover readouts are CSS
only. The detailed tabs, rate tools and exports are unchanged.
…-look settings

Every app-sent email (visit completed, invoice, payment reminder,
follow-up, contract signing request and signed copy, test email) now
carries an HTML alternative rendered from one table-based, inline-CSS
template, alongside the unchanged plain-text part. Colours come from the
company palette (or standard Lagoon teal), the logo travels as a CID
related part, and every customer or company string is escaped.

The outbox stores the HTML with each row so retries and approved
follow-ups deliver exactly what was queued. Settings > System gains a
"What customers see" card (palette on/off, logo, branded or plain text,
sign-off) with sandboxed live previews of the four customer emails.
The Contracts hub flagged sent, unsigned contracts after a fixed 14 days.
The threshold is now the contract_stale_days setting (1 to 90, default 14);
a missing or out-of-range stored value falls back to the default.
Restyle the Contract tab as outline | page | inspector on the existing
template back end. The page keeps click-to-edit, field chips, spa-only and
built-in blocks; the outline lists, reorders (buttons or drag) and adds
sections; the inspector holds the field palette, the shows-on switch and
built-in visibility, and docks under the selected section below 1100px.

The sample preview now renders built-in blocks with sample data, can preview
a pool-only contract (spa-only sections drop out) and uses the company's own
details where set. A rules card edits the unsigned-contract follow-up days.
Without JS the tab is still a plain form with a Save button and a field-code
reference.
…the environment

A fresh install has no owner account. Every page goes to /setup, which needs
a one-time setup code printed in the server log. The wizard creates the
owner (real name, own username, password stored only as a hash), offers
two-step sign-in (skipping it asks for confirmation and leaves a dashboard
reminder), then business details, prices, water and chemicals, palette and
layout, crew with temporary passwords shown once, and email. Each step
saves as you go; everything after the account can be skipped.

Upgrade note: APP_PASSWORD is no longer read or required. Existing
installs keep their 'owner' account and are asked once to add a name, pick
a username and set a new password. Owner recovery is now
`python -m app.manage reset-owner`, which prints a one-time reset link.
The business time zone is a setting (APP_TZ is only the default).
… pages

- The property form only saves an assignee who can hold a route (active
  technician or owner); a stale or forged id keeps the current one.
- Visit emails say "Serviced by" so an owner's visit isn't labelled
  Technician.
- Deactivating a customer records when, and analytics dates lost customers
  by it (older ones fall back to their last visit).
- The customer portal now loads the company palette, and the "Use the
  company palette" switch puts the portal and signing pages back on Lagoon.
… demo owner

The no-owner and upgraded-owner flags are cached per process; while either
is set the middleware now re-checks the database, so a seed script or
another worker ends setup mode everywhere. The CI browser job seeds an owner
through seed_sample_data.py (DEMO_OWNER_PASSWORD) instead of APP_PASSWORD.
…d follow-up emails

Each email is an ordered block list (heading, text with {field} tokens,
details, visit readings, attachment note, image, divider, sign-off) stored
as JSON per template, plus one shared email style (accent following the
palette or a validated hex, button shape). The plain-text and HTML parts
render from the same blocks; the defaults reproduce the previous emails
exactly. Uploaded images are re-encoded PNG/JPEG under 2 MB and travel as
CID parts. Admin > Emails edits them as plain forms with drag, field chips
and a live sandboxed preview on top, plus reset and a test send.
A one-page site in the app's own Aqua Atelier style: real screenshots of
the app on made-up demo data, a dose calculator that runs the same rules
as app/dosing.py (checked against it on 2,000 random readings), install
steps, FAQ, and links to GitHub, Docker Hub and releases. Deployed by
.github/workflows/pages.yml. Adds deploy/docker-compose.yml for running
the published image.
@dlommm
dlommm merged commit 78ce25e into main Oct 24, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant