mars-platform
Priyank DaveProject Brief — GE Powerzone Service Operations & Supply Chain Platform What this product is An internal web platform for a gas & electrical appliance service business. It sits as a wrapper and automation layer on top of two existing systems the company already lives in: ServiceM8 (field service management — jobs, technicians, scheduling) and Xero (accounting — invoices, payments). The office staff will do their day-to-day work inside this new platform; ServiceM8 continues to act as the underlying data store and technician mobile app, and the two stay in sync both ways. The goal is to replace a lot of manual copy-paste, email chasing, and switching between tabs with a single dashboard that tracks jobs, parts, quotes, suppliers, and payments, and automates follow-ups where a human is currently the glue. Users and roles Admin / office staff (Kylie, Linda, Wendy, Elaine): full access. Create jobs, quote, invoice, manage inventory, run analytics. Technicians (field): light access. Log in to report which parts they used from their van and view their assigned jobs. They do NOT re-enter anything they already put in ServiceM8. Owner / financial view: only Kylie and Elaine should see revenue/financial data. Financial section must be access-controlled because random visitors walk through the office. Core modules to build 1. Unified Operations Dashboard (the home screen) A single-pane-of-glass quick view that mirrors how ServiceM8 feels (so staff don't feel like they've left it), but with much better information density: Jobs by stage/queue: pending quote, P&A requested, quote sent, follow-up 1, follow-up 2, intervention required, parts on order, ready to schedule, awaiting invoice, etc. The queue structure should mirror ServiceM8 queues (currently ~5–8 queues, will grow as automation adds stages). "How long has this job been sitting here?" indicator per job (like the McDonald's drive-thru timer — visual cue when a job is aging out). Counts: jobs outstanding, jobs awaiting parts, quotes awaiting approval, overdue invoices. Jobs comparison by month across years (e.g. Jan 2024 vs Jan 2025 vs Jan 2026). Top clients by month/quarter (spend and job count). Better search than ServiceM8's — must treat multi-word queries as a phrase, not split into individual letters. Search across contacts, jobs, and job notes. Include refinements (date range, stage). Alerts panel: low stock, aged jobs, stuck follow-ups, overdue supplier responses. 2. Job Management List, detail, and create jobs (jobs can be created from the platform OR continue to be created in ServiceM8 — both must sync). Job status lifecycle: Created → Technician Assigned → Diagnosed → Quote Required → Quote Sent → Awaiting Approval → Awaiting Parts → Scheduled → Completed → Invoiced. Jobs can re-enter earlier stages (a completed job can revert to "quote needed" if a second visit finds more parts). Link jobs together by customer / appliance / issue so related jobs are visible to each other (prevents duplicate quoting). Every job has a job ID (format like 260503 — year + sequence). 3. Automated Work Order Ingestion Watches an inbox for incoming work orders (email + PDF attachments). Uses an LLM to extract: customer name & contact, site location, appliance make/model/serial, fault description, requested service. Creates the draft job in ServiceM8 via its API. Office confirms/edits before it goes live. 4. Technician Notes Cleanup (the most important automation per client) Technicians write raw, messy notes in the ServiceM8 "quote description" / "invoice description" field (spelling mistakes, stream-of-consciousness, mixed with internal commentary like who they spoke to). Office staff currently manually copy → clean → paste this into a customer-facing format for every quote and invoice. Trigger: when a technician checks out of a site / signs out of a job. Action: LLM takes the raw note, keeps the original raw version saved in the job's Notes section (audit trail), and writes a cleaned, formatted version back into the quote/invoice description. Format: top-level header with MAKE / MODEL / SERIAL / LOCATION in caps, then body. Preserve data loyalty: do NOT change part numbers the technician quoted — those are ordering-critical (if a tech wrote part X and office orders part X and it's wrong, the tech must not be able to say "I never gave you that number"). Keep the original raw note verbatim for this reason. Idempotency: mark formatted sections with an asterisk delimiter (e.g. *...*) so the cleaner knows what it already touched. On a 2nd or 3rd site visit, append a NEW cleaned block below the old one — do not re-clean and rewrite earlier ones, because the customer may already have received a quote referencing that text. Learns the house style from examples — the client already experimented with this in Claude and it worked. 5. Inventory / Parts Tracking (has to be custom — ServiceM8 doesn't do this properly) Parts catalog: ~16,000 items already, growing daily (new appliance models constantly). Fields per part: part name, internal SKU, supplier SKU(s) (can differ per supplier), optional photo (stored in AWS S3 — separate cost line), quantity, price, minimum-stock threshold. Storage locations: a main Warehouse + one stock location per technician van (Van 1, Van 2, …). Admin can add new storage locations (warehouse 2, van 6, etc.). Transfers: office moves stock Warehouse → Van when scheduling a job. Technicians do not pull stock themselves — the office does it from the admin UI (decided in the call to reduce technician friction). Usage logging: technicians, when they fit parts on a job, log what they used (either via the existing ServiceM8 mobile billing screen that syncs back, or a light mobile view in this new platform — ideally the former to avoid double entry). Low-stock alerts: for warehouse AND per-van (e.g. "Van 2 is down to 2 solenoids, normal load is 4 — alert office to top up"). Parts-to-job mapping: every part consumption maps to a job ID. A single job can have parts from 8+ different suppliers, so one job → many POs is normal. 6. Purchase Orders & Supplier Communication No formal PO system today — orders happen via supplier websites or Linda emailing "spares@hobart" style addresses asking for price & availability. Platform must support a PO record: supplier, parts, job ID reference, expected delivery, price, status. Supplier follow-up automation: once an email is sent to a supplier for P&A (price & availability), if no reply in a set window, auto-send follow-ups. Client wants aggressive cadence ("every 6 hours" was mentioned, realistic default 24h, configurable). After N automated follow-ups (default 3), STOP auto-sending and alert Linda to call. Requires a dedicated Gmail account for the platform so it can send-and-parse supplier replies. Supplier scorecard: average response time, delivery time, pricing consistency. 7. Customer Quote & Estimate Follow-Up Automation Triggered once the quote is manually sent for the first time (office sends the initial one, automation takes over after). Cadence: Day +3: friendly reminder email (+ optional SMS via ServiceM8's built-in SMS feature, using the existing template). Day +7 (or before the 2-week expiry): "your quote is about to expire" reminder. After that: automation stops, creates an "Intervention Required" alert so a human calls the customer. Don't become the "buy my fence" spam bot. Every automated send moves the job into a corresponding ServiceM8 queue (Follow-up 1, Follow-up 2, Intervention Required) so both systems stay visually aligned. Track: sent timestamp, response (approved / rejected / no response), approval history. 8. Payment & Financial Tracking (Xero integration) Paid vs unpaid invoices, overdue list, outstanding balance per customer. Connect to Xero directly (not via ServiceM8's Xero bridge) so we can customize analytics later. Financial section is role-gated — only Kylie/Elaine see dollar values. 9. Cross-Job Parts Reconciliation Engine (prevents duplicate billing) This is a later but critical piece. Real scenario: same customer, same appliance, two open jobs — office quotes the same part twice by accident. Centralized Parts Usage Ledger: ordered / allocated / installed events per part per job. Cross-job matching on (customer, appliance, issue, SKU, part name) using fuzzy/NLP matching (part names aren't standardized). Pre-quote validation: when a quote is being prepared, flag if the part was recently installed on a linked job or is already on another open quote. Show warning, allow manual override with a reason logged for audit. Auto-link related jobs by customer + appliance + issue. 10. Analytics & Reporting Jobs by month, year-over-year comparison. Component usage: most-used parts, high-failure parts, seasonal demand. Repair trends: most common failures by appliance type, repeat-failure patterns, average repair time. Technician efficiency: completion time, time waiting on parts / approvals, quote approval turnaround. Supplier performance (see §6). Top clients.
Comments (0)
Sign in to leave a comment
Project Tasks27
Implement Theme and Structure
As a user, I want the platform to visually match the mock-design pages exactly, so that the UI feels consistent and professional. This task covers applying the Mars-themed color palette (#F3F4F6 background, #FFFFFF surface, #1F2937 text, #FF5733 accent, #A0AEC0 muted), typography, spacing, and layout structure across all existing scaffold pages (home, login, signup, welcome, dashboard/overview, dashboard/ai-assistant, dashboard/settings). Remove any pages not referenced in the design or user flows. This task must remain independent of all others and be completed first.
Implement RBAC and Role Routing
As a user, I want to be able to use the backend API for role-based access control, so that sensitive financial data is protected and each persona sees only their permitted views. Implement RBAC middleware in FastAPI: Admin (full access), Technician (jobs + inventory logging only), Owner/Financial Manager (financials + analytics read-only). Protect the Financials route and any financial data endpoints. Include role assignment on login token.
Build Login Page
As a user, I want to be able to use the frontend login page to sign in securely, so that I can access the platform based on my role. Implement the Login page (v3) based on the existing JSX design. The login page is the entry point for all personas (Admin, Technician, Owner). On success, redirect to the Dashboard. Ensure role-based routing is applied post-login.
Implement ServiceM8 Sync Service
As a user, I want to be able to use the backend API for ServiceM8 integration, so that jobs, technician notes, queues, and billing data stay in sync in real time. Build the ServiceM8 sync feature module within the platform backend: webhook receiver (UUID → follow-up GET pattern), reconciliation cron job as backup, two-way job status sync, queue mirroring. Respect the 20,000 req/day rate limit. Scaffold with typed interfaces and stub implementations for all ServiceM8 API calls.
Implement Inventory API
As a user, I want to be able to use the backend API for inventory management, so that parts stock across warehouse and vans is accurate and transferable. Build FastAPI endpoints: parts catalog CRUD (~16,000 items), storage location management (warehouse + vans), stock transfer (warehouse → van), usage logging per job, low-stock alert triggers. Support part photo URLs via AWS S3 (stub S3 upload; actual S3 wiring optional). Include supplier SKU mapping per part.
Implement Financials API
As a user, I want to be able to use the backend API for financial tracking, so that paid/unpaid invoices, overdue balances, and revenue data are available to authorised roles. Build FastAPI endpoints: invoice list (paid/unpaid/overdue), outstanding balance per customer, revenue summary. All endpoints role-gated to Owner/Financial Manager. Note: Xero integration has been removed from scope; use internal data only.
Build Dashboard Page
As a user, I want to be able to use the frontend dashboard to view job queues, alerts, analytics summaries, and operational metrics, so that I have a single-pane-of-glass overview of all operations. Implement the Dashboard (v2) based on the existing JSX design. Features include: job queue cards by stage, aging indicators (drive-thru timer style), counts for outstanding jobs/quotes/overdue invoices, month-over-month job comparison, top clients, and an alerts panel (low stock, aged jobs, stuck follow-ups). The interactive galaxy map concept should be incorporated as the hero element. Linked from Login; links to Jobs, Inventory, Quotes, Suppliers.
Implement Jobs API
As a user, I want to be able to use the backend API for job management, so that jobs can be created, updated, and lifecycle-tracked from the platform. Build FastAPI endpoints: list jobs (with filters by stage, date, search), get job detail, create job, update job status, link related jobs (by customer/appliance/issue). Sync job mutations to ServiceM8. Support job ID format (year+sequence). Include technician-facing endpoints for viewing assigned jobs and logging parts.
Implement Suppliers PO API
As a user, I want to be able to use the backend API for purchase order and supplier communication, so that parts ordering and follow-ups are tracked and automated. Build FastAPI endpoints: PO CRUD (supplier, parts, job ID ref, delivery, price, status), supplier follow-up scheduler (configurable cadence, default 24h, max N attempts then alert), Gmail send/receive stub for supplier emails, supplier scorecard calculations (avg response time, delivery time, pricing consistency).
Implement Technician Notes Cleanup AI
As a user, I want to be able to use the AI API for technician note cleanup, so that raw messy notes are automatically formatted into professional customer-facing text without altering part numbers or raw data. Build LLM pipeline using LiteLLM/Langchain: trigger on technician checkout from ServiceM8 webhook, preserve raw note in job Notes section (immutable), write cleaned version to quote/invoice description (MAKE/MODEL/SERIAL/LOCATION format). Use asterisk delimiters for idempotency. Append new cleaned blocks on repeat visits; never rewrite existing ones. Use cost-appropriate model (Claude 4.6 Opus preferred). Accept user-provided API key.
Implement Work Order Ingestion AI
As a user, I want to be able to use the AI API for automated work order ingestion, so that incoming email/PDF work orders are parsed and draft jobs are created without manual data entry. Build LLM pipeline: watch dedicated inbox for work order emails + PDF attachments, extract (customer name/contact, site location, appliance make/model/serial, fault description, requested service), create draft job in ServiceM8 via API, present to office for confirmation/edit before going live. Use cost-appropriate model.
Build Jobs Page
As a user, I want to be able to use the frontend jobs page to list, view, create, and manage job lifecycles, so that I can track every job from creation to invoicing. Implement the Jobs page (v2) based on the existing JSX design. Covers: job list with status filters, job detail view (lifecycle stages: Created → Technician Assigned → Diagnosed → Quote Required → Quote Sent → Awaiting Approval → Awaiting Parts → Scheduled → Completed → Invoiced), job creation form, linked jobs view (by customer/appliance/issue), and technician view for assigned jobs and parts logging. Linked from Dashboard; links to Quotes.
Build Inventory Page
As a user, I want to be able to use the frontend inventory page to view and manage parts stock across warehouse and technician vans, so that I can track availability and trigger transfers. Implement the Inventory page (v2) based on the existing JSX design. Features: parts catalog list (~16,000 items), per-part details (SKU, supplier SKUs, photo, quantity, price, min-stock threshold), storage location views (Warehouse + per-van), transfer UI (Warehouse → Van), low-stock alerts display. Linked from Dashboard.
Build Quotes Page
As a user, I want to be able to use the frontend quotes page to send quotes to customers and track automated follow-ups, so that no quote falls through the cracks. Implement the Quotes page (v2) based on the existing JSX design. Features: quote list with status (sent, follow-up 1, follow-up 2, intervention required, approved, rejected), quote detail view, follow-up timeline display, manual override option with reason capture, approval history. Linked from Dashboard and Jobs.
Build Suppliers Page
As a user, I want to be able to use the frontend suppliers page to create purchase orders, track supplier responses, and view supplier scorecards, so that parts ordering is organised and automated. Implement the Suppliers page (v2) based on the existing JSX design. Features: PO creation form (supplier, parts, job ID, expected delivery, price, status), PO list/tracker, supplier response timeline, auto-follow-up status display, manual override for stopping automation, supplier scorecard (avg response time, delivery time, pricing consistency). Linked from Dashboard.
Build Financials Page
As a user, I want to be able to use the frontend financials page to view revenue, invoices, and overdue payments, so that financial health is visible to authorised roles only. Implement the Financials page (v2) based on the existing JSX design. Features: paid vs unpaid invoices, overdue invoice list, outstanding balance per customer, role-gated views (only Kylie/Elaine). Linked from Dashboard. Ensure RBAC guards are applied on this route.
Build Analytics Page
As a user, I want to be able to use the frontend analytics page to view operational reports and performance metrics, so that I can make data-driven decisions. Implement the Analytics page (v2) based on the existing JSX design. Features: jobs by month with YoY comparison charts, component usage (most-used/high-failure parts), repair trend breakdowns by appliance type, technician efficiency metrics, supplier performance charts, top clients. Linked from Dashboard.
Implement Quotes Follow-Up API
As a user, I want to be able to use the backend API for quote follow-up automation, so that customers are reminded on schedule without manual chasing. Build FastAPI endpoints and scheduler: trigger follow-up sequence on first quote send, Day+3 reminder email, Day+7 expiry warning, stop after N attempts and create Intervention Required alert. Push job queue updates back to ServiceM8. Log sent timestamp, response, approval history. Allow manual override with reason.
Implement Parts Reconciliation Engine
As a user, I want to be able to use the backend API for cross-job parts reconciliation, so that duplicate part billing across linked jobs is detected and flagged before quotes are sent. Build reconciliation engine: Centralized Parts Usage Ledger (ordered/allocated/installed events per part per job), cross-job fuzzy/NLP matching on (customer, appliance, issue, SKU, part name), pre-quote validation endpoint that flags duplicate parts on linked jobs, manual override with reason capture and audit log. Auto-link related jobs by customer + appliance + issue.
Implement Analytics API
As a user, I want to be able to use the backend API for analytics and reporting, so that operational metrics are computed and served to the analytics dashboard. Build FastAPI endpoints: jobs by month (YoY), component usage stats (most-used/high-failure parts), repair trends by appliance type, technician efficiency metrics, supplier performance scores, top clients by spend and job count. Aggregate from internal data.
Connect Jobs Page to API
As a user, I want to be able to use the frontend jobs page with live data from the backend, so that job list, details, and lifecycle updates are real and persisted. Wire the Jobs (v2) page to the Jobs API: fetch job list with filters, create/update job forms submit to API, lifecycle stage transitions call API, linked jobs display fetched from API. Handle loading/error states.
Connect Inventory Page to API
As a user, I want to be able to use the frontend inventory page with live data, so that stock levels, transfers, and low-stock alerts reflect real inventory state. Wire the Inventory (v2) page to the Inventory API: parts catalog listing/search, transfer form submissions, low-stock alert display. Handle loading/error states.
Connect Quotes Page to API
As a user, I want to be able to use the frontend quotes page with live follow-up data, so that quote statuses and automation timelines are accurate. Wire the Quotes (v2) page to the Quotes Follow-Up API: quote list with live statuses, follow-up timeline display, manual override form. Handle loading/error states.
Connect Suppliers Page to API
As a user, I want to be able to use the frontend suppliers page with live PO and scorecard data, so that purchase orders and follow-up statuses are tracked in real time. Wire the Suppliers (v2) page to the Suppliers PO API: PO list/creation form, follow-up status display, manual override, supplier scorecard charts. Handle loading/error states.
Connect Financials Page to API
As a user, I want to be able to use the frontend financials page with live invoice and revenue data, so that financial overviews are accurate and role-gated. Wire the Financials (v2) page to the Financials API: invoice lists, overdue display, revenue summaries. Enforce role-gate on the frontend route. Handle loading/error states.
Connect Analytics Page to API
As a user, I want to be able to use the frontend analytics page with live report data, so that charts and metrics reflect current operational performance. Wire the Analytics (v2) page to the Analytics API: all chart data fetched from API, loading/error states handled, role-appropriate data displayed.
Connect Dashboard Page to API
As a user, I want to be able to use the frontend dashboard with live operational data, so that job queues, alerts, counts, and analytics summaries are real and up to date. Wire the Dashboard (v2) page to Jobs, Inventory, Quotes, Analytics, and Suppliers APIs: job queue cards, aging indicators, alert panel, counts, YoY charts, top clients. Handle loading/error states and real-time refresh.
Mars Platform
Sign in to your account
No comments yet. Be the first!