{ "schema": 1, "version": "69f7733", "updated": "2026-10-16", "note": "THE source of truth for the dashboard manual (D68). app/manual/index.html and app/manual/manual.md are generated from this file by scripts/build-manual.py; the build fails when a launcher tile, a config flag or a proxy action is missing here, when a flag state drifts from app/config.js, or when the generated files are stale. No secrets, no customer data, no prices.", "app": { "name": "PPTG Dashboard", "url": "https://dash.portapottytogo.com/app/", "manualUrl": "https://dash.portapottytogo.com/app/manual/", "jsonUrl": "https://dash.portapottytogo.com/app/manual/manual.json", "markdownUrl": "https://dash.portapottytogo.com/app/manual/manual.md", "whatItIs": "The office tool of Porta Potty To Go (PPTG): orders, invoices, collections, recurring billing, customers, routes and reports for two markets. GoHighLevel (GHL) is the accounting book (contacts, invoices, payments); Stripe holds the saved cards; the dashboard is the collector (cobrador) and the screen people work in.", "signIn": "Google sign-in with a company account. The role (owner, manager, office, finance, field) decides which tiles you see. Preview mode (access key) is NOT a sandbox: it talks to the real server and real GHL / Stripe data — for safe tests, mock the endpoints or use the robot contact only.", "views": "Phone view (tiles) everywhere; Office view (left navigation, dense tables, side panel) on desktop. The header's View switch (Auto / Phone / Office) is remembered per user and device; Auto = Office at 1200 px and wider; phones (< 640 px) see no switch.", "markets": [ { "id": "wpb", "name": "West Palm — PPTG", "ghlLocation": "6N89N8vbtVWNcj2VpNak", "active": true }, { "id": "orl", "name": "Orlando — partner", "ghlLocation": "7Ismp3jGLVSOZ2737Cfo", "active": true } ] }, "screens": [ { "id": "launcher", "title": "Home (Inicio)", "path": "#/home (Office) · the tile grid (Phone)", "tile": null, "purpose": "The start page: greeting, today's numbers (today's stops, open quotes, invoices due / overdue = open invoices at or past their due date, won this month = paid invoices issued this month), the Ask or dictate box, and the tiles your role may open.", "howToGetThere": "Sign in. The PPTG logo or the back arrow on any screen returns here.", "whatYouSee": [ "Number chips (a source that could not be read shows '?')", "All / West Palm / Orlando buttons and a 'By market —' line (a market that failed says 'unavailable')", "'Recurring drafts awaiting activation' line when there are any (opens Invoices)", "Ask or dictate (the Assistant)", "Tiles: Sales & Billing, Operations, Tools & Reports, and the Manual link" ], "actions": [ { "label": "All / West Palm / Orlando", "whatItDoes": "Re-filters the numbers by market.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Recurring drafts awaiting activation", "whatItDoes": "Opens Invoices, where they are activated.", "sideEffects": "none", "needsConfirmation": false } ], "gotchas": [ "The number chips are not links (in the Office view the Home tiles are)." ] }, { "id": "new-order", "title": "New Order (Nueva orden)", "path": "tile New Order · Office: #/orders", "tile": "new-order", "purpose": "Build an order for a customer and turn it into an invoice (factura) or a quote (cotización): customer, service address, lines from the catalog, delivery date, notes, Job/PO, tax.", "howToGetThere": "Tile 'New Order', '+ New' in Office, 'New order' on a customer profile, or a draft's 'Edit draft'.", "whatYouSee": [ "1 Customer: search by phone / name / email, or create one ('Save customer')", "Billing market badge (decided by the service address; Override needs a reason)", "2 Service address (site address, ZIP prices the zone, optional place name); 'Schedule pickup' and 'Adds to an active site' options", "3 Order: the catalog by category, quantity, price; 'Prices from …' tells how old the prices are", "Payment: our pay page by default (saves the card), 'Enter card now', 'Use saved card'; 'Send GHL's link instead' is the secondary path", "Send as QUOTE, Preview, Send as INVOICE, Save invoice draft, Save quote draft" ], "actions": [ { "label": "Send as INVOICE", "whatItDoes": "The confirm sheet (lines, tax, total, where it goes); Confirm creates the invoice in GHL, makes our pay page and sends it by email (and text where enabled). It also books the delivery on the Google Calendar (and a pickup when ticked), and for recurring lines drafts an inactive GHL recurring template (or enrolls the site in billing when mixedOrders is on).", "sideEffects": "email", "needsConfirmation": true }, { "label": "Payment: Enter card now", "whatItDoes": "Creates the invoice and opens our pay page in staff mode to type the card; the screen waits until it is paid.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Payment: Use saved card", "whatItDoes": "Creates the invoice and charges the contact's saved card.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Send as QUOTE", "whatItDoes": "Creates the estimate (cotización) and sends it by email / text.", "sideEffects": "email", "needsConfirmation": true }, { "label": "Preview", "whatItDoes": "How the customer will see it. Read only.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Save invoice draft (Guardar borrador)", "whatItDoes": "Creates (or updates, when editing a draft) a GHL draft invoice. Nothing is sent.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Save quote draft", "whatItDoes": "Creates a GHL estimate as a draft; send it from Quotes.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Save customer / Save contact", "whatItDoes": "Creates the GHL contact, or saves its edits from the customer strip.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Override (market)", "whatItDoes": "Bills the order in the other market. A reason is required and goes on the invoice.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Create recurring template (draft) — on the result screen", "whatItDoes": "Drafts an inactive GHL recurring invoice template for the recurring lines, after an in-app confirm.", "sideEffects": "ghl", "needsConfirmation": true } ], "gotchas": [ "Leaving an order with unsaved lines asks 'Discard this order?' first.", "The market follows the SERVICE address, not the billing address.", "A county with no tax configured in that market blocks invoicing (fail loud) — add the tax in GHL first.", "Tax exempt needs a reason (and the certificate on the contact).", "'Prices from … ()' next to 'Refresh catalogue' tells how old the prices are; older than 2 days is flagged (the owner can update them in Admin).", "Every customer invoice email also goes to the owner as a '[Copy]' (CONFIG.invoiceOwnerCopy; when no GHL contact has that email, CONFIG.ownerContactId). A copy that was not sent is said on the result screen and in a toast." ] }, { "id": "customers", "title": "Customers (Clientes)", "path": "tile Customers · #/customers/:", "tile": "customers", "purpose": "Find any customer and see everything: contact, sites, invoices, payments, notes (History), recurring billing; edit the contact.", "howToGetThere": "Tile 'Customers', or click any customer name anywhere (every name is a link).", "whatYouSee": [ "Search, '+ New customer'", "The profile: phone, email, card on file, last invoice", "Sites (service addresses): '+ Add site', Remove", "Invoices with the shared invoice menu", "Orders (GHL opportunities)", "History: invoices, payments, refunds, voids, notes, orders, recurring billing — searchable; add an internal note" ], "actions": [ { "label": "+ New customer", "whatItDoes": "Creates the GHL contact (read back).", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Edit", "whatItDoes": "Edits the GHL contact (CC emails, place reference, tax exemption); every save is read back.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "+ Add site / Save site", "whatItDoes": "Saves a service address on the contact's sites (read back).", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Remove (site)", "whatItDoes": "Removes a saved site; click twice (\"Confirm remove?\").", "sideEffects": "ghl", "needsConfirmation": true }, { "label": "New order / New invoice", "whatItDoes": "Opens New Order with this exact contact.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Add note", "whatItDoes": "Writes an internal note on the contact (read back).", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Recurring… (Sites card)", "whatItDoes": "Opens this customer's recurring templates (active and draft, in that market) with 'Cancel schedule' on each: an in-app confirm ('Keep it' does nothing), then GHL stops making invoices from it — re-read to confirm it shows cancelled, and a 'RECURRING CANCELLED' note goes on the customer's History. Invoices already made stay as they are. There is no Pause (no proxy action yet).", "sideEffects": "ghl", "needsConfirmation": true } ], "gotchas": [ "'Back' returns to the screen the name was clicked on." ] }, { "id": "collections", "title": "Collections (Cobranza)", "path": "tile Collections", "tile": "collections", "purpose": "The past-due queue for both markets, worst first, with the reminder ladder: the screen suggests the next step, a human clicks.", "howToGetThere": "Tile 'Collections' (its badge counts past-due invoices in both markets).", "whatYouSee": [ "Per-market totals and a market filter", "Each invoice: days over, last reminder, the NEXT step", "Send reminder (the ladder dialog), Call, Promised to pay, and the shared invoice menu" ], "actions": [ { "label": "Send reminder", "whatItDoes": "Opens the reminder dialog with the ladder's step and a preview; Send emails / texts the customer and records a note.", "sideEffects": "email", "needsConfirmation": true }, { "label": "Promised to pay", "whatItDoes": "Hides the invoice from the queue until the promised date (recorded as a note). Asks the date in an in-app date box; Cancel records nothing.", "sideEffects": "ghl", "needsConfirmation": false } ], "gotchas": [ "Nothing auto-sends: GHL's own reminders are switched off on purpose.", "A market that failed to load says 'unavailable', never 0.", "When the invoice has no stored pay link, the reminder dialog sends GHL's own invoice email / text instead.", "Call is a phone link (tel:)." ] }, { "id": "billing", "title": "Billing (Cobro recurrente)", "path": "tile Billing", "tile": "billing", "purpose": "The recurring-billing engine (billing.php): which sites are enrolled, what the next cycle charges, holds that need approval, the daily run, and the activity timeline.", "howToGetThere": "Tile 'Billing'.", "whatYouSee": [ "Recurring charging ON / OFF (the kill switch), last run, enrolled / on hold / charged so far, daily limit", "Enrolled sites per market with the per-cycle amount and a market filter", "Holds (first cycle, amount changed, over a cap)", "Waiting for a saved card", "Activity timeline by name (raw ids in the tooltip and in 'Show raw log')" ], "actions": [ { "label": "Turn charging ON / OFF", "whatItDoes": "The kill switch of automatic charges.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Authorize charge (a hold)", "whatItDoes": "Charges the saved card NOW for that held cycle.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Preview today", "whatItDoes": "Shows what today's run would charge. Read only.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Enroll (waiting for a saved card)", "whatItDoes": "Enrolls the site in recurring billing once its card is saved.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Remove (waiting for a saved card) / Unenroll", "whatItDoes": "Stops future automatic charges for that site (the card stays saved; no money moves).", "sideEffects": "none", "needsConfirmation": true } ], "gotchas": [ "The first cycle of every site is always held for approval.", "Charges stop at the gates (tolerance, jump vs. last cycle, per-charge cap, daily total).", "The engine sends no receipt of its own: GHL sends it when the payment is recorded." ] }, { "id": "payments", "title": "Invoices (Facturas)", "path": "tile Invoices (data-nav payments) · Office: #/invoices", "tile": "payments", "purpose": "Every invoice in both markets: search, filter, sort, and the invoice menu (details, links, send, preview, record payment, refund, edit, void).", "howToGetThere": "Tile 'Invoices'.", "whatYouSee": [ "Search (number, name, company, email, phone; address and notes once the invoice's Details were opened)", "Filters: market, past due, status, dates, amount, county, source", "'Recurring drafts awaiting activation' card when there are any", "Rows with status, market and the invoice menu" ], "actions": [ { "label": "Details", "whatItDoes": "The invoice as GHL has it. 'Edit line items' (draft, sent, overdue, partially paid: qty, price, name, description, add / remove lines) saves to GHL and, for a sent invoice, asks whether to resend; 'Edit full order' opens a draft in New Order.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Open payment link / Copy link", "whatItDoes": "Our pay page link (refreshed when it expired), or GHL's link for invoices made in GHL.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Send invoice / Send receipt", "whatItDoes": "The channel dialog (email / text) with a preview; Send contacts the customer. On a draft it first asks: our pay page or GHL's standard email (GHL's is not previewed).", "sideEffects": "email", "needsConfirmation": true }, { "label": "Preview", "whatItDoes": "How the customer will see it (our templates). Read only.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Send pay page (saves card)", "whatItDoes": "Makes our pay page (pays the invoice and saves the card), then the email / text choice. A DRAFT is finalized in GHL first (it becomes SENT) — cancelling the choice leaves it sent, nothing reaches the customer.", "sideEffects": "email", "needsConfirmation": true }, { "label": "Charge saved card", "whatItDoes": "Charges the card on file for the amount due (only shown when the contact has a card).", "sideEffects": "money", "needsConfirmation": true }, { "label": "Record payment", "whatItDoes": "Records a cash / check / Zelle payment in GHL (no card is charged); open invoices only; click twice.", "sideEffects": "ghl", "needsConfirmation": true, "flag": "recordPayments" }, { "label": "Refund", "whatItDoes": "Full or partial refund to the card (owner only), also on partially paid invoices; 'Paid outside the card' records the refund only; click twice. A full refund also voids the invoice.", "sideEffects": "money", "needsConfirmation": true, "flag": "refunds" }, { "label": "Edit draft", "whatItDoes": "Opens a draft in New Order, fully editable; 'Save changes' updates the same draft.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Edit invoice (sent, unpaid)", "whatItDoes": "Opens a sent / overdue / partially paid invoice in New Order; 'Save changes to invoice #N' updates the SAME invoice (number, dates, status kept; an 'Updated : …' line in its notes and on the customer's History); never below what was already paid. Then 'Resend updated invoice' sends one message with a fresh pay link — the old link stops working. If GHL refuses the update: 'Replace invoice' (new draft, old one voided).", "sideEffects": "ghl", "needsConfirmation": false, "flag": "editSentInvoices" }, { "label": "Void", "whatItDoes": "Two steps: confirm, then a required reason (saved on the customer). Disabled on paid invoices — refund instead.", "sideEffects": "ghl", "needsConfirmation": true }, { "label": "Send reminder", "whatItDoes": "A payment reminder with the pay link (email, text where enabled), recorded as a note.", "sideEffects": "email", "needsConfirmation": true }, { "label": "Open customer", "whatItDoes": "The customer's profile.", "sideEffects": "none", "needsConfirmation": false }, { "label": "Activate (recurring drafts card)", "whatItDoes": "Activates a drafted GHL recurring invoice schedule, charged to the customer's card each cycle.", "sideEffects": "money", "needsConfirmation": true }, { "label": "Recurring… (invoice menu)", "whatItDoes": "Opens this customer's recurring templates (active and draft, in that market) with 'Cancel schedule' on each: an in-app confirm ('Keep it' does nothing), then GHL stops making invoices from it — re-read to confirm it shows cancelled, and a 'RECURRING CANCELLED' note goes on the customer's History. Invoices already made stay as they are. There is no Pause (no proxy action yet). Shown when the customer has a live template.", "sideEffects": "ghl", "needsConfirmation": true } ], "gotchas": [ "The SAME invoice menu is in Invoices, Collections, Customers, Office and the New Order result screen.", "The customer-facing title is 'PPTG Order — · Job/PO '; internal stamps (zone, county) ride a 'Dashboard ref:' line in the terms.", "Paying through GHL's link does not save the card; our pay page does.", "Cancel an activated recurring schedule: 'Recurring…' on the customer card or the invoice menu → 'Cancel schedule'. Pause is not in the dashboard (no proxy action) — pause it in GHL." ] }, { "id": "quotes", "title": "Quotes & Follow-Up (Cotizaciones)", "path": "tile Quotes & Follow-Up", "tile": "quotes", "purpose": "Open estimates (cotizaciones) per market: edit drafts, send them, and turn an accepted quote into an invoice.", "howToGetThere": "Tile 'Quotes & Follow-Up'.", "whatYouSee": [ "Open quotes per market with status", "Row buttons: Edit (drafts), Send to customer / Resend, Create invoice (accepted)", "'+ New quote' (opens New Order)" ], "actions": [ { "label": "Edit → Save draft", "whatItDoes": "Edits a draft quote in GHL.", "sideEffects": "ghl", "needsConfirmation": false }, { "label": "Send to customer / Resend", "whatItDoes": "Sends the estimate to the customer.", "sideEffects": "email", "needsConfirmation": true }, { "label": "Create invoice (accepted quote)", "whatItDoes": "Creates the real invoice (due on receipt) with the quote's lines and the county tax, then sends OUR pay page (pays and saves the card; stored on the invoice) by email + text. If the pay page cannot be made it sends GHL's link and says so. One request every 3 s, so it takes about half a minute.", "sideEffects": "email", "needsConfirmation": true }, { "label": "+ New quote", "whatItDoes": "Opens a blank New Order.", "sideEffects": "none", "needsConfirmation": false } ], "gotchas": [ "There is no automatic follow-up: a human resends." ] }, { "id": "pickup", "title": "Schedule Pickup (Recoger unidades)", "path": "tile Schedule Pickup", "tile": "pickup", "purpose": "Request a pickup for an active rental: the request is written on the customer as a note for dispatch. It does NOT book the calendar, stop billing or remove the route stop — dispatch does those.", "howToGetThere": "Tile 'Schedule Pickup'.", "whatYouSee": [ "Active rentals in both markets", "Search by name or phone", "'Request pickup' per customer" ], "actions": [ { "label": "Request pickup", "whatItDoes": "One in-app dialog: the date (or 'ASAP', required) and an optional dispatch note, then 'Save pickup note' writes 'PICKUP REQUESTED — — ' on the contact. Cancel saves nothing. It does NOT book the calendar and does NOT stop billing (the dialog says so).", "sideEffects": "ghl", "needsConfirmation": false } ], "gotchas": [ "After the request: book the pickup on the calendar, stop the billing ('Recurring…' on the customer card → Cancel schedule, or Billing → Unenroll) and adjust the route." ] }, { "id": "routes", "title": "Routes (Rutas)", "path": "tile Routes", "tile": "routes", "purpose": "A read-only live view of today's route from HelloTracks (no HelloTracks login needed): stops by date, address search and a map.", "howToGetThere": "Tile 'Routes' (the only tile the field role sees).", "whatYouSee": [ "Today's Route: date picker, Today, Refresh", "Address Search", "Map" ], "actions": [], "gotchas": [ "Target stops per driver and day: about 20-26 on a local route, 15-20 on a far route." ] }, { "id": "calendar", "title": "Calendar (Calendario)", "path": "tile Calendar", "tile": "calendar", "purpose": "Deliveries, pickups and services on the Google calendars the routing sync reads.", "howToGetThere": "Tile 'Calendar'.", "whatYouSee": [ "'Connect Google Calendar' (first time)", "WPB / ORL switch", "Events by calendar and day", "Create / edit an event (events the dashboard or you created; others open in Google Calendar)" ], "actions": [ { "label": "Connect Google Calendar", "whatItDoes": "Connects the Google account (OAuth).", "sideEffects": "none", "needsConfirmation": false }, { "label": "Create event / Save", "whatItDoes": "Writes the Google calendar right away (the routing bot syncs it the next afternoon).", "sideEffects": "calendar", "needsConfirmation": false }, { "label": "Delete (this occurrence / the event)", "whatItDoes": "Deletes from the Google calendar.", "sideEffects": "calendar", "needsConfirmation": true } ], "gotchas": [ "Same-day changes are manual for the dispatcher; Orlando is not synced by the bot.", "Only events the dashboard created, or that you created, can be edited here." ] }, { "id": "week-organizer", "title": "Week Organizer (Organizador semanal)", "path": "tile Week Organizer", "tile": "week-organizer", "purpose": "A read-only weekly view from HelloTracks: seven day columns with the stop count and up to 25 delivery / pickup / service chips per day.", "howToGetThere": "Tile 'Week Organizer'.", "whatYouSee": [ "Prev / This week / Next", "Seven day columns with a stop count", "DEL / PU / SVC chips" ], "actions": [], "gotchas": [ "Moving stops between days or drivers is done in HelloTracks, not here." ] }, { "id": "price", "title": "Price Lookup (Precios)", "path": "tile Price Lookup", "tile": "price", "purpose": "The rate card by ZIP and service (the same catalog New Order uses).", "howToGetThere": "Tile 'Price Lookup'.", "whatYouSee": [ "A service address with suggestions (the ZIP is taken from it) -> zone", "Prices per service for that zone" ], "actions": [], "gotchas": [ "Trailers cost the same in every zone.", "Price increases apply to new orders only." ] }, { "id": "reports", "title": "Reports (Reportes)", "path": "tile Reports", "tile": "reports", "purpose": "Revenue by month: totals by market, zone and status, a separate sales-tax-by-county table, CSV exports.", "howToGetThere": "Tile 'Reports'.", "whatYouSee": [ "Prev / This month / Next, Refresh", "'By market' lines (WPB / ORL), zone and status totals", "'Sales tax by county' table (taxable, tax, lines) with its own Export CSV", "Export CSV of the invoices" ], "actions": [ { "label": "Export CSV", "whatItDoes": "Downloads exactly what the month view shows (market column WPB / ORL).", "sideEffects": "none", "needsConfirmation": false }, { "label": "Export CSV (tax by county)", "whatItDoes": "Downloads the county tax table.", "sideEffects": "none", "needsConfirmation": false } ], "gotchas": [ "What Orlando billed: Reports, pick the month, read the ORL line in 'By market' (or the CSV, market = ORL).", "Drafts and voided invoices are excluded.", "A past month reads until the start of THAT month (one request every 3 s, so a far month takes a few seconds). A market that could not be read fully is said in red above the totals ('Orlando: incomplete — …; these totals are LOW') — refresh, or check that market in GHL." ] }, { "id": "assistant", "title": "Assistant (Asistente)", "path": "tile Assistant · the Ask or dictate box", "tile": "assistant", "purpose": "A read-only beta: ask in words (prices by ZIP, customer lookups, invoice status) or dictate; it answers, it takes no action.", "howToGetThere": "Tile 'Assistant' or the Ask or dictate box on Home.", "whatYouSee": [ "Chat", "Microphone (dictation)", "With the assistantDrafts flag: draft cards and customer candidates that open in New Order" ], "actions": [ { "label": "Open draft in New Order", "whatItDoes": "Fills New Order with the dictated lines; nothing is sent.", "sideEffects": "none", "needsConfirmation": false, "flag": "assistantDrafts" } ], "gotchas": [ "The Assistant never sends or charges anything by itself.", "With assistantDrafts on, 'Open in New Order' asks 'Discard this order?' first when New Order has unsaved lines; Cancel keeps that order." ] }, { "id": "admin", "title": "Admin", "path": "tile Admin (owner)", "tile": "admin", "purpose": "Prices (catalog) per market, config summary and live health checks (owner).", "howToGetThere": "Tile 'Admin' (owner only).", "whatYouSee": [ "Prices (catalog): each market's last update ('West Palm: N products, M prices · from