Screen-by-screen Specification — Part 2

Date: 31 Oct 2026
Based on: Development Plan (Revision 8), Specification Part 1, PPW reports audit (§22.7)
UI prototype: Design canvas "Preservation SaaS UI" — Billing, Clients & pricing, Vendors, Contractors & crew, Reports, Report: AP & AR, Import client payments, Report: contractor report card
Status: Draft; review by the user pending. Sections marked "Proposal" are not yet approved.

Part 2 covers: money rules, billing screens, payments and import, cuts/chargebacks, QuickBooks, clients and pricing, vendors and crew, reports, settings, subscription and SaaS admin. The general rules (§1) and roles (§3) of Part 1 also apply here.

14. General money rules

• Unit: all amounts are integer cents, USD. Rounding only on the line total (half-up); invoice total = sum of the line totals.
• Two sides: every order has one client invoice (money in, AR) and one contractor bill per contractor (money out, AP). If an order has more than one contractor, each gets a separate bill.
• Cash basis (Confirmed): income and expenses are counted on the payment date; invoice and bill dates are used for ageing.
• Tax: no tax engine; optional manual tax line on the invoice (Proposal, plan §9.6).
• Changes: a sent invoice or a paid bill is not edited directly; changes are made through an adjustment line, cut, chargeback or credit, with history.
• Numbering (Proposal): invoice INV-YY-NNNN, bill B-YY-NNNN, sequential per company; the prefix can be changed in company settings.

15. Client invoice lifecycle

• Order approval is not required before the invoice is complete (some clients want the invoice together with completion; plan §5.5). However, a warning is shown if it is marked Complete before Approved.
• Short pay: if the client pays less, the difference is automatically proposed as a cut (§19); the office confirms it.
• Goes to the Incomplete invoices report: an Approved order whose invoice is Draft, or Complete but not Sent for more than 3 days (number of days is a setting).

16. Contractor bill lifecycle

• Condition for approval (Proposal): order Approved (QA passed). "Pay contractor only once the client has paid" can be turned on in company settings.
• Deductions: the contractor's share of a chargeback is deducted from the next approved bill (§19); a separate line "Chargeback CB-…" on the bill.
• The contractor owner sees their own bills in the app/portal (prices and paid status); crew do not see them.

17. Billing screen

At the top: AR ageing (0–30, 31–60, 61–90, 90+), AP ageing, QuickBooks status and error list.

Tabs:

Header buttons: Import client payments (§18), Export to Excel, "Invoice N approved orders" (Draft → Complete bulk).

18. Payments and client payment import

18.1 Manual payment

Amount, date, method (Check / ACH / Wire / Card / Other), check or reference #, how much to which invoice/bill (can be split across several invoices), note. An overpayment stays as a client credit (applied to the next invoice).

18.2 Import — three paths (Confirmed, §22.7)

1. Excel / CSV: column mapping (saved per client).
2. PDF remittance: a template once per client (which part holds WO #, invoice #, paid amount, check #). For a scanned PDF without text, manual entry with the PDF shown alongside.
3. Email text paste: the same template method (Altisource, Safeguard-style emails).

Steps: Upload → Check matches → Apply (UI: "Import client payments").

Rules:

• Matching is by client WO #; if not found, by our invoice #; if not found, by loan # + address.
• Nothing changes until Apply is clicked. After Apply, the source file is attached to each payment; it goes to QuickBooks on the next sync.
• A warning if the same file (hash) or the same check # + client is imported a second time.
• Half-done work can be "Save and finish later".

18.3 Our standard CSV format (Proposal)

Used when the client does not provide its own format or the office builds the file itself. First row is the header; UTF-8; dates YYYY-MM-DD or MM/DD/YYYY.

The template file can be downloaded from Reports → Import client payments.

19. Cuts, chargebacks and write-offs

Who bears it — Confirmed (not in PPW): chosen on every cut and chargeback:

• Contractor: the full amount is deducted from the next contractor bill.
• Company: the contractor gets the full amount; the company's margin is reduced.
• Split: divided by amount or %.

Default in company settings (Proposal: Contractor). Can be changed until the contractor's share has been deducted; after that only by the Owner, with history.

Mass write-off / chargeback (Reports):

• Mode: Write-off or Chargeback.
• Filters: date range, remaining amount (greater/less than), client, contractor, work type.
• Select rows in the results; in chargeback mode, amount and who bears it on each row.
• Clicking "Make write-offs / Make chargebacks" shows a preview (how many, total amount) → confirm → recorded as one batch; the whole batch can be undone if none of it has gone to QuickBooks.
• Comment required.

20. QuickBooks Online sync

• One direction: ours → QuickBooks (plan §9.0 mapping: client → Customer, contractor → Vendor, invoice → Invoice, bill → Bill, payment → Payment/Bill Payment, cut/chargeback → Credit Memo/Vendor Credit).
• Connect: Settings → Integrations → Connect QuickBooks (OAuth). Owner/Accountant only.
• Mapping: work type/item → QuickBooks Item; income/expense account; contractor → Vendor (if missing, created on the next sync, with 1099 flag).
• When: Complete invoices, approved bills and every payment in a batch every 15 minutes; "Sync now" button.
• Errors: item not mapped, vendor missing, closed period in QuickBooks, token expired — listed on the Billing screen, each with "Fix" and "Retry".
• If something changes on our side after it has gone to QuickBooks, an update is sent; we do not read things changed by hand in QuickBooks (v1).

21. Clients & pricing

21.1 Client

Fields: name, client ID (the vendor/client ID they assigned), billing email and address, pay terms, invoice delivery method (portal / email / PDF), client WO # format (for the duplicate check), status (Active/Inactive).

Customers: customer list under the client (Fannie Mae, Wells Fargo…). Comes from the client with the order (Confirmed); if not in the list, proposed as a new customer at import.

Client settings (tabs): Prices · Billing & dates · Photo rules · Forms & instructions.

21.2 Price catalog and rules

• Catalog: the company's item list: item, unit (each, cu yd, sq ft, hour…), default client price, default contractor price, QuickBooks item.
• Client price: catalog price or the client's own price.
• Rule conditions: client, customer, work type, state, lot size range, loan type.
• Selection rule: the most specific rule wins (greater number of matching conditions); on a tie, the newer one. The order line shows which rule the price came from.
• Discount/markup: client discount % (can be state-based), contractor discount %, markup %. Shown on the line: client price, contractor price, margin.
• Price changes do not affect earlier orders; a Draft invoice has an "Apply new prices" button.
• v1 limit (Confirmed): one pricing system; the rule types are finalised after learning the pilot company's actual method.

21.3 Billing & dates

Contractor due offset (e.g. client due − 3 days), invoice due offset, rush surcharge, trip charge, minimum invoice, "invoice before approval allowed" (yes/no).

21.4 Photo rules (three levels: company → client → order)

Minimum photos (total and per category), required categories, gallery photo permission, max distance (ft), date range check, future timestamp forbidden, EXIF edit forbidden, block or only flag on mock location, delivery copy (resize, header text, file name pattern).

21.5 Forms & instructions

Required forms and instructions by client/work type; added automatically when the order is created (Part 1 §7.1).

21.6 Work types

The company's catalog: name, whether it can be recurring, whether it is an inspection, default tasks, default photo categories, active. Starts from a starter template (Grass cut, Trash out, Winterization, Re-key, Initial secure, Inspection…).

22. Vendors (contractors) and crew

22.1 Vendor directory — "Find vendors"

Filters: status (Active / Onboarding / Inactive), state, ZIP or county coverage, work type, on-time % below, has open orders, chargebacks (90 days), insurance expiring within 30 days, no W-9, no background check, pay method, 1099, no QuickBooks link, search (name, email, phone, EIN last 4).

Columns (selectable): vendor, status, contact, phone, email, vendor ID, EIN last 4, states, work types, on time, open orders, chargebacks, crew users, insurance expires, W-9, pay by, QuickBooks.

Actions: saved views, Excel export, email the selected, open profile.

22.2 Adding a vendor — four paths (Confirmed)

1. Type it in: Company (legal name*, DBA, EIN/SSN*, W-9 tax type, vendor ID, status) · Contact (main contact*, email*, phone, address) · Coverage & work (states, ZIP/county, work types, contractor discount %) · Documents · Payment (method, bank, terms, QuickBooks vendor) · Notes.
2. Excel / CSV: column mapping → check (Ready / Already exists → update? / Problem rows) → import. Template download.
3. From PDF: reads the W-9 and insurance certificate (ACORD 25) and fills in the fields; each field shows its source ("W-9 line 1") and status (Read / Not found / Matches you). The office verifies and saves; the PDFs are attached to documents.
4. Invite: a link to the vendor; they provide the information and documents themselves; Active once the office approves.

Duplicate: if the same EIN or email already exists, a new one is not created; adding to the existing one is proposed.

22.3 Sensitive information

EIN/SSN and bank number encrypted; only the last 4 digits shown. The Owner can see the full value, logged each time. The Accountant can see the bank number (for pay runs), with logging.

22.4 Documents

W-9, general liability, workers' comp, license, background check, other. Each has an expiry date. Notification to the vendor and the office 30/7/0 days before expiry. On expiry (company setting): only a warning, or block new order assignment.

22.5 Crew

• Confirmed: crew members are added by the vendor themselves from the app (name, phone/email → invite). There is no crew import for the office.
• Each crew member has a separate login (Confirmed); they do not see prices or payments.
• On the Contractors & crew screen the office sees: app version, last sync, items pending to send from the phone, last check-in.
• A crew member is counted as an active user for billing (§25).

22.6 Performance (same calculation as the report card)

On-time %, late %, average days in field, returned at QA, chargebacks, still in field.

23. Reports

23.1 General rules (report engine)

• One engine: filters → group by → column picker → saved views → Excel/CSV export.
• Date range at most 1 year; no date needed if an invoice # or check # is given.
• Export: more than 5,000 rows runs as a background job; when finished, a notification and an email link (valid for 7 days). An "Exports ready" list.
• Reports are view and export only; no money changes are made from reports (unlike PPW; done from Billing).
• Processors do not see money reports; contractors see only their own.
• Loan # always masked.

23.2 Report list (11 in v1)

Calculation rules:

• Days in field = ready for office − received (days). If there is no ready for office, up to today, labelled "Still in field" (to avoid PPW's 5-digit bug).
• Late = ready for office > due date (end of day, property timezone).

Later: Order link queue (plan §22.3).

24. Settings

25. Subscription and active-user billing

Price (Confirmed, plan §11.1.1): per company $100/month, including 5 users; after that $10/month per active user.

• Active user: logged in at least once in the month or was assigned to an order. Office, contractors and crew are all counted. No charge for inactive/blocked accounts.
• Same contractor in two companies: each company pays for its own membership.
• Added mid-month: prorated (Stripe per-seat).
• Counting: active count at month end → quantity update in Stripe → invoice. The Owner's Subscription page lists this month's active users so far (why each was counted: "logged in Oct 12" / "assigned WO-…").
• Trial (Confirmed Nov 2026): 14 days, no card; manual activation for the pilot company (plan §11.3).
• Non-payment (Confirmed Nov 2026): 7 days grace → read-only (uploads continue in the field app so photos are not lost) → suspension after 30 days → export window → deletion.
• Cancel: 30-day export window (download all photos and data), then deletion; removed from backups within at most 90 days (in the Terms).
• Storage (Confirmed Nov 2026): usage is shown on the Subscription page and not charged for now; a storage tier is decided later from real usage.

Subscription page: plan, this month's estimated bill (base + extra users), active users list, storage usage, payment method (Stripe portal), invoices, cancel.

26. SaaS admin (our own, not visible to customers)

• Companies: list, plan, active users, storage, last activity, status (trial / active / past due / suspended / cancelled).
• Manual activation and trial extension (pilot).
• Support access: time-limited "Login as" when the customer grants permission, all actions logged.
• System health: upload queue, failed jobs, QuickBooks sync errors (all companies), storage growth.
• No company's business data (prices, photos) is shown directly on admin screens; only through support access.

27. Open questions