System Requirements Document

Service Operations & Inventory Management Platform

1. Introduction

This document outlines the requirements for developing the Service Operations & Inventory Management Platform, a solution designed to streamline service operations and inventory management. The platform will integrate with ServiceMate to enhance operational efficiency, reduce manual administrative tasks, and provide a centralized interface for managing jobs, inventory, and supplier communications.

The solution will enable:

• Automated work order ingestion and job creation.
• Structured technician notes for standardized documentation.
• Real-time job tracking and status monitoring.
• Automated follow-ups for quotes, estimates, and supplier communications.
• Comprehensive inventory management, including van-specific stock tracking.
• Operational analytics and reporting.

The platform will serve as a wrapper around ServiceMate, allowing technicians to continue using ServiceMate for job-related tasks while providing additional functionality for office staff. The design prioritizes security, scalability, and usability.

2. System Overview

The platform addresses key operational challenges faced by service-based businesses, including manual work order processing, unstructured technician notes, limited job status visibility, inefficient supplier communication, and lack of digital inventory tracking. By automating these processes and providing a unified dashboard, the platform will improve efficiency and reduce administrative overhead.

3. Functional Requirements

• As a User, I should be able to automate work order ingestion from emails and create jobs in ServiceMate.
• As a Technician, I should be able to add notes that are automatically cleaned and structured by the system.
• As an Admin, I should be able to track job progress and status in real time.
• As an Admin, I should be able to automate follow-ups for quotes and estimates.
• As an Admin, I should be able to manage inventory, including van-specific stock levels and low-stock alerts.
• As an Admin, I should be able to automate supplier communication for price and availability checks.
• As an Admin, I should be able to view operational analytics and reporting.

4. User Personas

1. Admin:

   • Full access to all platform features.
   • Responsible for managing jobs, inventory, and supplier communications.
   • Oversees operational analytics and reporting.

2. Technician:

   • Access to van-specific inventory.
   • Logs parts usage and updates job status.
   • Adds notes for jobs, which are cleaned and structured by the system.

3. Financial Staff:

   • Access to financial tracking and reporting modules (future scope, not implemented in this phase).

5. Visuals Colors and Theme

The platform will adopt a professional and modern light theme to reflect its focus on operational efficiency and usability. The following design tokens will be used:

• primary: #4A90E2 (Indigo Blue)
• primary_light: #A6C8F5 (Light Indigo Blue)
• secondary: #F5A623 (Amber Orange)
• accent: #50E3C2 (Mint Green)
• highlight: #F8E71C (Bright Yellow)
• bg: #F7F9FC (Light Gray)
• surface: rgba(255, 255, 255, 0.9) (White with slight transparency)
• text: #333333 (Dark Gray)
• text_muted: #888888 (Muted Gray)
• border: rgba(0, 0, 0, 0.1) (Subtle Black)

6. Signature Design Concept

Interactive Workflow Map:
The homepage will feature an interactive workflow map that visually represents the service operations pipeline. Users will see a dynamic flowchart with the following stages: Work Order Ingestion, Technician Notes Processing, Job Tracking, Supplier Communication, and Inventory Management. Each stage will be represented as a clickable node with animations triggered on hover or click.

• Hover Interaction: Nodes will expand slightly and display a tooltip with a brief description of the stage.
• Click Interaction: Clicking a node will zoom into that stage, revealing detailed metrics and actions (e.g., jobs in progress, pending supplier responses).
• Animation: The flowchart will animate smoothly as users navigate between stages, using spring physics for transitions.
• Technology: Built using @react-three/fiber for 3D rendering and framer-motion for animations.

This concept will make the platform visually engaging while providing an intuitive way to access key functionalities.

7. Interaction Model & Motion Direction

• Landing Page Interaction Model: Parallax
  The landing page will feature layered depth effects, with decorative elements (e.g., gears, tools, and service icons) moving at different speeds as the user scrolls. Real content will scroll naturally, while background elements create a sense of depth and immersion.

• Internal Pages Interaction Model: Static
  Internal pages such as the dashboard, job tracking, and inventory management will prioritize clarity and usability, with minimal motion effects limited to hover transitions and dropdown animations.

8. Non-Functional Requirements

• Performance: The platform must load within 3 seconds on a standard broadband connection.
• Scalability: The system should support up to 10,000 jobs and 1,000 users without performance degradation.
• Security: All data must be encrypted in transit and at rest. Role-based access control will be implemented.
• Usability: The platform must be mobile-friendly and accessible via modern web browsers.
• Reliability: The system must have 99.9% uptime, with automated monitoring and alerting for critical failures.

9. Tech Stack

• Frontend: Vite React + TypeScript + Shadcn
• Backend: FastAPI
• Database: PostgreSQL (with Alembic for migrations)
• AI Models: GPT 5.1 for technician notes cleanup and structuring
• Local Orchestration: Docker, docker-compose
• Server-Side Orchestration: Kubernetes
• Storage: AWS S3 for part images
• Email Automation: Gmail API for supplier follow-ups

10. Assumptions and Constraints

• The platform will not include Xero integration in this phase.
• ServiceMate API access will be provided by the client.
• The system will rely on predefined templates for technician notes cleanup.
• The platform will be deployed as a web application, with no dedicated mobile app.

11. Glossary

• ServiceMate: A field service management software used for job scheduling and tracking.
• Work Order Ingestion: The process of automatically extracting job details from emails.
• Technician Notes Cleanup: The process of structuring and formatting notes added by technicians.
• Van-Specific Inventory: Inventory tracking specific to individual service vehicles.
• AWS S3: Amazon Web Services Simple Storage Service, used for storing images and files.

12. Next Steps

1. Finalize requirements and obtain client sign-off.
2. Begin development of Phase 1 deliverables (work order ingestion, technician notes cleanup, and dashboard).
3. Schedule regular progress reviews and testing sessions.

13. Action Items

1. ServiceMate API Access: Create a test admin user and provide credentials.
2. LLM API Key: Provide OpenAI API key for automation tasks.
3. AWS S3 Setup: Configure storage for part images.
4. Technician Notes Template: Provide sample notes for cleanup and structuring.
5. Supplier Email Templates: Provide existing templates for follow-up automation.
6. Job Creation Data: Specify fields to extract from emails for job creation.
7. Inventory Data: Provide initial stock levels and supplier details.

14. Contact Points

• Client Contact: Kylie Ellwood
• Project Liaison: Mary Ai (Ethical Edge Solutions)
• Preferred Communication: Email

15. Deployment

The platform will be deployed incrementally to ensure smooth adoption:

1. Initial deployment for work order ingestion and dashboard.
2. Rollout of automation features.
3. Final deployment of analytics and reporting modules.