Screen-by-screen Specification — Part 1
Date: 30 Oct 2026
Based on: Property-Preservation-SaaS-Final-Development-Plan.md (Revision 6+), PPW reference findings (§22)
UI prototype: Design canvas "Preservation SaaS UI" (12 screens)
Status: Draft; review by the user pending. Product name PPHub (Confirmed, 31 Oct 2026).
Part 1 covers: general rules, order lifecycle, roles, and the order, QA and mobile app screens. Part 2 will cover: billing, clients and pricing, contractors, settings and SaaS admin.
1. General rules
- Tenant: every record has a
company_id; a user sees only the data of companies where they have an active membership. - Time: all times stored in UTC; displayed in the property's timezone (e.g. "EDT"). The due date is the end of the day in the property's local time.
- Money: integer cents, USD.
- History: every change on an order goes to history (who, when, what, old and new value).
- Sensitive fields: lockbox, key and gate codes, and loan # are masked; pressing "Show" requires permission and the viewing event goes to history.
- Delete: orders are not deleted, only Cancelled; photo delete is office-only, with history (the original stays in the archive as long as the company is active).
2. Order status and transitions
| Status | Meaning | Who changes it | Next status |
|---|---|---|---|
| Unassigned | No contractor | System (new order) | Assigned, Cancelled |
| Assigned | Contractor/crew set, work not started | Office | In field, Unassigned, Cancelled |
| In field | Checked in or first photo taken | App (automatic) | Ready for office, Cancelled |
| Ready for office | Crew tapped "Send to office" and the server has received all items | App, after server confirmation | Follow up, Approved, Cancelled |
| Follow up | Office requested corrections | Office (reason required) | Ready for office |
| Approved | QA passed, Office lock on | Office | Invoiced |
| Invoiced | Client invoice sent | Office/Accountant | Closed |
| Closed | Client paid and contractor paid | System (when both payments match) or Accountant | — |
| Cancelled | Cancelled | Office (reason required) | — (only the Owner can reopen) |
- Unread: not a separate status; a "crew has not opened yet" marker on an Assigned order. Alert when the time in the company setting has passed.
- Resubmit count: +1 each time it goes to Ready for office; "2nd submit" in the header.
- Tags: created by the company itself (e.g. RUSH, Waiting on client); they do not change the status.
- Recurring: each visit is a separate order; the parent series holds the frequency, limit and cut-off. The next visit is created when the previous one is Approved.
3. Roles
| Role | Main responsibilities |
|---|---|
| Owner | Everything; billing settings, users, subscription |
| Manager | Orders, assignment, QA, clients and pricing; not subscription |
| Office Processor/QA | Create and edit orders, assignment, QA, follow up |
| Accountant | Invoices, bills, payments, QuickBooks; not order edit |
| Contractor owner/lead | Own company's orders, assign to crew, view own bills |
| Crew | Only their own assigned orders; does not see prices or payments |
In the screen tables below: E = edit, V = view, — = none.
4. Dashboard (office)
Purpose: see at a glance what is urgent at the start of the day.
| Section | Content | Click |
|---|---|---|
| KPI tiles | Unassigned, Due today, Overdue, Ready for office, Follow up, Ready to invoice | Work order list with filter |
| Needs attention | Overdue, rush without contractor, follow up older than 24 hours, unread, not checked in | Order detail |
| Waiting for QA | Ready for office orders, photo count, summary of checks | QA review |
| Field sync | How much work is still waiting to be sent from which crew's phone, last online time | Contractor detail |
| Money this month | Unpaid client invoices, owed to contractors, ready to invoice; QuickBooks errors; expiring documents | Billing / Contractors |
Roles: Owner, Manager, Processor see everything; Accountant only the money section; not contractors.
5. Work order list
Saved views: All open, Rush, Overdue, Ready for office, My orders, Recurring + users can save their own views (filters, columns, sort).
Filters: status, client, customer, work type, state, ZIP, contractor, crew, tag, due date, client due date, received date, rush. Search: WO #, client WO #, loan #, address, ZIP.
Default columns: Status, WO #, Work type, Client, Contractor, Due, Client due, Address, City, State, Photos, Tags. Columns can be chosen.
Bulk actions: assign contractor, change due date, add/remove tag, export (CSV/Excel), cancel (with reason).
Rule:
- Overdue due date in orange and bold; not color alone, also sorted to the top.
- Page size 25/50/100.
| Role | View | Bulk actions |
|---|---|---|
| Owner, Manager, Processor | All | E |
| Accountant | V | Export only |
| Contractor owner | Own company's orders (app/portal) | — |
6. Work order detail
Header: WO #, status, resubmit count, work type, tags, address, client, customer, masked loan #, loan type; actions: Edit, Duplicate, Print PDF, Review & approve. Below: contractor due, client due, contractor, crew, assigned admin, office lock.
Tabs:
- Overview — dates (received, start, estimated complete, complete, cancel, sent to client), rush, BATF, occupancy, lot size, access codes (masked); client instructions (automatic from rules, source shown); tasks (task, qty, unit, required photos, qty completed in the field, source).
- Notes — order notes and property notes kept separate; property notes appear on every order at the same address.
- Bid & completion — bid lines: item, qty, contractor price/total, client price/total, photos, client decision (Waiting/Approved/Rejected); past bids; client bid PDF; "Send to client" (manual delivery record). Approved line → new task.
- Photos — grouped by category; QC check summary (timestamp, GPS, date range, max distance); upload, move/copy, download PDF; go to QA view.
- Forms — form, whether required, status (number of answers), who answered.
- Invoice — client invoice and contractor bill side by side: lines, price, adjusted price, total, discount, paid. (Details in Part 2)
- History — all changes in chronological order.
Edit rule: while Office lock is on, no one except Owner/Manager can change the order or photos.
| Tab | Owner/Manager | Processor | Accountant | Contractor owner | Crew |
|---|---|---|---|---|---|
| Overview | E | E | V | V (without prices) | V (without prices) |
| Notes | E | E | V | E (order notes) | E (order notes) |
| Bid & completion | E | E | V | E (own prices) | E (without prices) |
| Photos | E | E | V | E (before lock) | E (before lock) |
| Invoice | E | V | E | V (own bill) | — |
| History | V | V | V | — | — |
7. New work order / CSV import
7.1 Manual entry
Sections: Client and work · Property · Dates and assignment.
| Field | Required | Rule |
|---|---|---|
| Client | Yes | From the client list |
| Customer | No | The client's customer list |
| Client WO # | No | Warning if duplicate within the client |
| Work type | Yes | The company's work type catalog |
| Rush | No | None / 24h / 48h |
| BATF, Recurring | No | If Recurring: frequency, limit, cut-off |
| Address, City, State | Yes | Geocoded to lat/long; if the same address is found, linked to the existing property |
| ZIP | Yes in the US | Optional internationally |
| Loan #, loan type, mortgagor, lockbox, key/gate code, lot size | No | Codes encrypted |
| Client due | Yes | — |
| Contractor due | No | If not given, per client rule (e.g. client due − 3 days) |
| Contractor, crew, assigned admin | No | Contractor list sorted by ZIP coverage |
Automatically added: tasks, instructions, photo rules and required forms from the client × customer × work type × loan type rules; shown on the right before saving.
Buttons: Save work order, Save and add another.
7.2 CSV / Excel import
- Choose file + choose client → that client's saved mapping applied automatically.
- Match columns: each column → a field or "Not imported"; work type value mapping (e.g. "Lawn Maint" → Grass cut); save mapping.
- Check: Ready / Duplicate (same client WO #) / Rejected (with reason, row number). Duplicates skipped by default, optionally updated.
- Import → background job; notification when finished; download rejected rows.
8. QA review
Layout: queue on the left (Ready for office, oldest first), photo grid in the middle, metadata of the selected photo on the right.
Order summary chips: photo count vs minimum, flagged count, forms complete, check-in time and distance.
Photo metadata panel: taken (device time + timezone), uploaded, GPS (with accuracy, or "Missing"), distance from property, source (in-app camera/gallery), device and app version, original file name; crew's reason if flagged.
Automatic checks (per client rules):
| Check | Flagged when |
|---|---|
| Timestamp | No capture time |
| GPS | No location |
| Date range | Capture time before the order's start/check-in or after complete |
| Max distance | Farther from the property than the client's limit (e.g. 300 ft) |
| Minimum photos | Too few in total or in any required category |
| Gallery | Gallery photo when the client forbids gallery |
Actions:
- On a photo: Accept exception (reason must be entered) / Ask for new photo.
- On the order: Send back (follow up; reason required, shown in the crew's app) / Approve and lock.
- Approve is disabled until all flags are resolved; Owner/Manager can override (recorded in history).
Roles: Owner, Manager, Processor = E; Accountant = V; contractor = —.
9. Android app — My jobs
- Company name at the top (switcher if working for more than one company).
- When offline, a persistent banner: how many jobs are on the phone and that work is safe.
- Filters: Today, This week, Follow up.
- Job card: work type, status, address, city, due, WO #, sync status (Saved on phone / N photos waiting / Not downloaded yet).
- When online, assigned jobs, instructions, forms and property notes download automatically.
10. Android app — Job
- If the office has a follow up, the reason is shown at the top.
- Check in / Check out: GPS and time; if required by client or contractor setting, the camera will not open without check-in.
- Photos: have/need and status for each required category.
- Tasks: checkbox and qty.
- Forms, add bid, client instructions, property note.
- Send to office: if not all requirements are met, shows what is missing; after sending it goes to the sync queue; "Sent" is not shown before server confirmation.
11. Android app — Camera
- Category chips (Before, After, the client's categories, Bid); a count on each.
- Metadata preview in the viewfinder: date-time and timezone, GPS accuracy, distance from property.
- When offline, a "photos stay on phone" marker.
- Shutter: original file + app metadata (category, order, crew, device, app version, capture time, GPS) into the local database.
- Remaining requirement ("After: 2 more needed").
- Add from gallery: if the client allows it; source marked "Gallery", current location not used as the capture location.
12. Android app — Sync
- Status: Waiting, Uploading (progress), Failed (retry time + Retry now), Sent to office (time of server confirmation).
- Wi-Fi only setting.
- Space used by waiting photos and the phone's free space.
- Rule: the local copy is deleted only after server confirmation; logout blocked while unsynced items exist; duplicates prevented by a device-generated ID for every photo and submission; uploads resumable.
13. Coming in Part 2
- Billing: client invoices, contractor bills, payments, cuts and chargebacks, client payment import, ageing, QuickBooks sync.
- Clients & pricing: client settings, price catalog and rules, photo rules, work types.
- Contractors & crew: company, crew, documents, coverage, performance.
- Settings, users and roles, notifications, subscription and active-user billing.