PestControlOS Operations Platform

The PestControlOS Operations Platform is a full-featured field operations app for pest control companies. It is built in Java for Android and backed by Firebase (Authentication, Firestore, Storage) with optional Cloud Functions and LLM APIs.

The primary goal is to streamline field work: scheduling, contracts, jobs, reports, messaging and leads, while giving admins and technicians tailored tools and in-app notifications. The app runs on the device and talks to Firebase (Auth, Firestore, Storage, optional Cloud Functions, App Check) and to external AI providers (Groq, Hugging Face) where configured.

• Android (Java), Firebase backend
• Scheduling, contracts, jobs, reports, messaging, leads
• Role-based access for admins and technicians
• In-app notifications only (no FCM push)

Users sign in with email/password via Firebase Authentication. On successful login a central SessionManager loads the user’s staff profile, role and permissions from Firestore.

From the login screen you can enter "Offline User" mode. In this mode no Firebase services are used; only a limited set of features are available (create reports, view reports, logout). Offline users cannot upload reports to Firebase or access notifications, jobs, contracts, leads or messaging.

All screens respect the logged-in user’s role. Admins can assign work, view multiple calendars and edit contracts/jobs. Technicians can perform work and generate reports but cannot delete jobs or contracts.

• Firebase Auth (email/password)
• Offline User mode: reports only, no Firebase
• Role-aware UI (super_admin, admin, tech)

A daily schedule shows fixed half-hour slots from 08:00–17:30. Technicians can tap a slot to add a job, contract visit or follow-up. Jobs, contracts and follow-ups are differentiated by colour and label.

When creating or editing an event you can specify a custom start and end (e.g. 08:30–15:00). Long-press an event and drag it to another slot to move it; the start time snaps to the new slot and duration is preserved.

Admins can view other technicians’ schedules (all technicians on one calendar) for dispatch and office coordination. WorkManager schedules in-app reminders about 30 minutes before an event; reminders are cancelled if the event is completed or rescheduled.

A home-screen widget displays today’s date and the next three jobs. Data is cached when Work View is opened so the widget works even after logout.

• Daily view 08:00–17:30, 30-minute slots
• Custom times and drag-and-drop reschedule
• Combined calendars for admins
• In-app reminders ~30 minutes before events
• Home-screen widget (today + next 3 jobs)

Contracts are stored in Firestore collections named "{ContractKey} Contracts", where ContractKey comes from the user’s staff profile. This keeps documents stable even if login usernames change.

Search and filter by status: "Behind", "Due" or "Up-to-date" to prioritise visits. Open the customer address in Google Maps, update a visit as done, or create a report directly from a contract entry.

Admin users can assign a contract to another technician; the assigned user receives an in-app notification. Year-based report browsing: contract reports live under ReportsYY/ in Firebase Storage; select the year and the app lists matching PDFs (ignoring case, spaces, underscores). Offline users can browse local reports only.

• Technician-scoped collections ({ContractKey} Contracts)
• Status counters: Behind / Due / Up-to-date
• Maps, mark visit done, create report
• Admin assignment with in-app notification
• Reports by year (ReportsYY/)

New service jobs can be added via the Jobs screen or directly from the calendar. Admins choose the technician from a dropdown; the assigned technician receives an in-app notification.

Technicians can accept jobs, view customer details, update progress and schedule follow-ups. Completion prompts update the calendar and remove future reminders. Follow-ups have dedicated screens and appear alongside other events in Work View.

A separate "Management Jobs" section tracks office/administrative tasks. Admins can create and complete these independently of technician work.

• Job creation and assignment (in-app notification)
• Accept, complete, schedule follow-ups
• Follow-ups in Work View
• Management jobs for admin tasks

The app uses iText to generate PDFs. Built-in templates include: service reports (rodent initial, routine, call-out, external), general reports (4pt/6pt/8pt/12pt), action forms, quotations (general and bird), and service agreements. Reports include the business logo and compress automatically.

A "Password protect PDF" checkbox encrypts the PDF with an owner password (viewing/printing allowed; editing requires the password). Technicians and customers can capture signatures on a dedicated screen; images can be attached and embedded in the PDF.

When logged out, users can build custom headers with their own logo, header text, watermark and header blocks. Named templates are stored locally and can be selected later. Logged-in users use the default PestControlOS template for consistency.

• Service reports: rodent (initial, routine, call-out, external), general (4/6/8/12-point)
• Action forms with optional owner-password encryption, technician + client signatures, image attachments
• Quotations: point-based (4/6/8/12pt), bird control with optional 30% deposit, custom line-item
• Service agreements with dual signature capture (technician + client)
• Environmental Risk Assessments (ERA): Toxic and Non-Toxic workflows
• Invoices: initial setup, monthly maintenance, feature update, custom, with VAT calculation
• RAMS (Risk Assessment and Method Statement) documents
• All PDFs: iText7, auto-compressed, optional owner-password encryption
• Offline custom template engine with logo, watermark, header blocks, named template storage

General quotations use 4, 6, 8 or 12 line items with VAT and totals calculated automatically. Bird quotations are tailored for bird control with an optional 30% deposit. Company contact (email, mobile) is pulled from the staff profile.

Service agreements can be created with signature fields and saved as PDFs, then uploaded to Firebase Storage or kept locally.

• Point-based quotations (4/6/8/12pt)
• Bird quotations with optional 30% deposit
• Company details from staff profile
• Service agreements with signatures

Leads are recorded in Leads with commission values, invoice numbers, payment status and materials cost. Admins can mark invoices as paid and update materials cost. Technicians can add and view leads assigned to them but cannot mark invoices paid or edit materials.

Edits to leads can trigger an in-app notification to the responsible technician, keeping an audit trail.

• Lead capture with commission tracking
• Invoice and payment status
• Admin: mark paid, edit materials
• Technician: view/add assigned leads only

Conversations are stored in Firestore with IDs derived from participant ContractKeys (direct chats and a shared group channel). Messages can be marked urgent; non-urgent messages can expire automatically via optional Cloud Functions.

The app has its own notification inbox per staff member (notifications/{StaffID}/items). Job assignment, contract assignment and lead updates fan out to admins. There are no system/FCM notifications or status-bar alerts; everything stays inside the app. Unread counts show on the home screen; tapping a notification deep-links to the relevant screen (Work View, Contracts, Jobs, Messaging).

• 1:1 and group chat in Firestore
• Urgent vs non-urgent (optional retention)
• In-app notification inbox only
• Deep-links to Work View, Contracts, Jobs, Messaging

When location permissions are granted, each device publishes its last known GPS position to Firestore every 15 minutes. A cleanup worker deletes stale locations after 30 minutes. The last known location is cached locally so admins can view it offline. Only users with admin/oversight role have the UI to view staff locations; Firestore rules should restrict reads to authorised admins.

• Periodic GPS updates (e.g. every 15 minutes)
• Offline cache of last location
• Admin-only location finder UI

A dedicated search screen lets authorised admins search across jobs, contracts, leads and reports from a single interface. Results show the entity type and link to the appropriate activity. This feature is limited to admin accounts because it touches multiple collections.

• Search jobs, contracts, leads, reports
• Results link to the right screen
• Admin-only access

The Route Planner module uses the Google Directions API to calculate optimised multi-stop routes for technicians. Admin users input multiple job site addresses and the system determines the most efficient route order.

Once calculated, the optimised route can be exported as a professionally formatted PDF via BestRoutePdfGenerator, giving technicians a printed or shareable route card for their day.

• Google Directions API multi-stop route optimisation
• Ordered stop list with address and estimated travel segments
• PDF route card export via BestRoutePdfGenerator
• Admin-controlled; read-only for technicians

The Site Map module provides a freehand canvas drawing tool (SiteMapCanvasView) for creating and annotating floor plans or site layouts per contract. Technicians can draw, annotate, and label site-specific information directly on their device.

Maps are stored and listed per contract, giving both field technicians and admin staff persistent visual site records that can be referenced on every visit.

• Freehand canvas drawing with annotation layer (SiteMapCanvasView)
• Stored and listed per contract in Firestore
• Persistent site visual records across visits
• Accessible to assigned technician and admin

The PDF Converter module allows users to convert any PDF document to a Word (.docx) file or extract its plain text content. For scanned PDFs or image-based documents, ML Kit OCR is used to perform on-device optical character recognition before conversion.

This enables field technicians and admins to extract, edit, or repurpose content from externally sourced PDFs without leaving the app. Access is controlled by the canConvert permission flag on the user's staff profile.

• Convert PDF to Word (.docx) or extract plain text
• ML Kit OCR for scanned and image-based PDFs
• On-device processing with no third-party upload required
• Gated by canConvert permission flag

The PDF Editor provides a multi-page PDF viewer with a draw overlay for annotating existing PDF documents. Users can add freehand annotations directly onto the pages of any stored PDF, useful for marking up site surveys, reports, or external documents.

• Multi-page PDF viewer with draw annotation overlay
• Annotate any stored PDF document
• Persistent annotation layer saved with the document

The Invoicing module allows admins to create invoices linked directly to contracts in Firestore. Invoice templates cover initial setup, monthly maintenance, feature updates, and custom invoices. VAT and totals are calculated and previewed before generation.

Generated invoices are uploaded to Firebase Storage and written to the Firestore ledger, creating a persistent, auditable financial record per contract.

• Invoice templates: initial setup, monthly maintenance, feature update, custom
• Full VAT calculation and totals preview
• Uploaded to Firebase Storage and written to Firestore ledger
• Contract-linked for auditable financial records
• Admin-only; linked to ContractKey for data scoping

Staff can submit bug reports or feature requests directly from within the app. Super_admin can review submissions, set a cost estimate, estimated delivery days, and status. Clients can agree or disagree on feature quote proposals.

The full lifecycle, submission, review, pricing, approval, and status updates, is managed in-app with long-press editing for admins. This replaces email-based support workflows with a structured, in-platform change management process.

• Staff submit bugs or feature requests in-app
• Super_admin sets cost, days, and status per item
• Client agree/disagree on feature quote proposals
• Full lifecycle: submission → review → pricing → approval → resolution
• Long-press admin editing; structured in-platform change management

Super_admin accounts have full employee management capability: create, edit, and deactivate staff accounts from within the app. Each staff member is assigned a role (super_admin, admin, tech) and individual permission flags (canSearch, canConvert, etc.) that control feature access beyond their base role.

Staff profiles store name, email, role, ContractKey (used for data scoping and routing), and optional custom flags. Deactivating a staff member revokes their access without deleting their historical records.

• Create, edit, and deactivate staff accounts in-app
• Role assignment: super_admin, admin, tech
• Individual permission flags: canSearch, canConvert, and others
• ContractKey-based data scoping and routing
• Deactivate without deleting historical records

A native Android home screen widget displays the current date and the next 3 scheduled work events. The widget data is populated by WorkViewWidgetHelper whenever Work View is opened or updated, and is cached locally so it remains visible even after logout.

• Shows today's date and next 3 scheduled jobs
• Updated by WorkViewWidgetHelper on Work View changes
• Locally cached and visible after logout
• No additional permissions required beyond Work View access

Field technicians can perform Toxic or Non-Toxic ERA assessments. An activity collects the user’s name and launches either the Toxic or Non-Toxic ERA flow. Each flow guides the technician through the risk-assessment checklist and generates a PDF when complete.

• Toxic and Non-Toxic ERA flows
• Checklist-driven, PDF output

User identity and permissions are controlled via Firestore: StaffID, Role (super_admin, admin, tech), Name/Email/Number, ContractKey, and optional "Can" flags. On login the app resolves UID → StaffID, then loads users/{StaffID} and populates SessionManager with Role, ContractKey and permissions.

super_admin has full access (global search, location sharing, API key management). admin can assign work, manage contracts and jobs, update commissions, and view multiple calendars. tech can view their own work, create and upload reports, and manage their own contracts but cannot delete jobs or contracts.

• Roles: super_admin, admin, tech
• ContractKey for collections and assignments
• No hardcoded staff IDs in app logic

Client: Android (Java), XML layouts, RecyclerView, WorkManager, Material components. Data & auth: Firebase Authentication, Firestore, Firebase Storage for PDFs and attachments. PDF generation: iText with automatic compression and optional owner-password encryption. Optional Node.js Cloud Functions for scheduled cleanup (e.g. message retention).

• Android (Java), Firebase (Auth, Firestore, Storage)
• iText for PDFs; optional Cloud Functions