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.

• iText PDFs: service, general, action forms, quotations
• Password protection option
• Signatures and images embedded in PDFs
• Offline "My Template"; PestControlOS template when logged in

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

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