**Prepared by:** Oditha

**Date:** 23 January 2026

**Version:** 1.0

**Reference:** [FRD - HoReCa Field Operations & Workflow Management](https://www.notion.so/FRD-HoReCa-Field-Operations-Workflow-Management-2f7cd2773bc548c9a2595d856f15ac15?pvs=21)

---

## Overview

This document provides high-level process flows for the Lion HoReCa Excellence system to help developers and stakeholders understand the end-to-end business processes.

---

## 1. Workflow Configuration Process

### 1.1 Workflow Creation Flow

**Actor:** System Administrator

**Steps:**

1. Admin logs into System Admin portal
2. Navigate to Workflow Management
3. Create new workflow
    - Enter workflow name, description, category
    - Set status (Active/Inactive)
    - Add icon and color
4. Add workflow steps
    - Define step order, name, description
    - Select question type (Selection/Text Area)
    - Configure step attributes (mandatory, skip, remarks)
    - Add sample photos (optional)
5. Configure conditional logic (optional)
    - Define rules for step visibility
    - Set AND/OR conditions
    - System validates no circular dependencies
6. Configure service request triggers (optional)
    - Map step options to SR categories
    - Assign SR templates
7. Save workflow
8. Workflow becomes available for template assignment

**Exit Conditions:**

- Success: Workflow saved and ready for use
- Cancel: No changes saved
- Error: Validation fails, user corrected

---

### 1.2 Workflow Group Template Creation Flow

**Actor:** System Administrator

**Steps:**

1. Navigate to Workflow Group Templates
2. Create new template
    - Enter template name, description
    - Set icon, color, status
3. Add workflows to template
    - Select workflows from available list
    - Set mandatory/optional flag per workflow
    - Define execution order
4. Preview template configuration
5. Save template
6. Template becomes available for outlet assignment

**Exit Conditions:**

- Success: Template saved
- Cancel: No changes saved

---

## 2. Outlet Configuration Process

### 2.1 Outlet Setup Flow

**Actor:** System Administrator

**Steps:**

1. Navigate to Outlet Management
2. Create new outlet (or import CSV)
    - Enter outlet name, address, coordinates
    - Set outlet type (Restaurant, Hotel, Café, Bar)
    - Assign territory/region
    - Assign users (LSR, TM, SM hierarchy)
3. Assign Workflow Group Template
    - Select template from dropdown
    - System loads all workflows from template
4. Customize workflows (optional)
    - Enable/disable specific workflows
    - Enable/disable specific steps
    - Add outlet-specific steps
5. Configure brands
    - Select must-have brands
    - Select optional brands
6. Configure equipment
    - Add coolers (quantity, type, serial numbers)
    - Add branding materials
    - Add pouring materials
7. Save outlet configuration
8. System validates and creates outlet
9. Outlet becomes available in mobile app for assigned users

**Exit Conditions:**

- Success: Outlet configured and active
- Error: Validation fails, user corrects

---

## 3. POSM Audit Scheduling Process

### 3.1 Automated Audit Task Generation

**Actor:** System (Automated)

**Trigger:** 20 days after previous audit completion

**Steps:**

1. Daily cron job runs at 02:00 IST
2. System queries all outlets with completed audits
3. For each outlet where last_audit_date + 20 days = today:
    - Create new audit task
    - Set scheduled_date = today
    - Set due_date = today + 5 days
    - Assign to outlet's primary TM
    - Link norms sheet based on outlet type
4. Send notification to TM
5. Task appears in TM's "My Audits" list in mobile app

**Exit Conditions:**

- Success: Audit tasks created and notifications sent
- Error: Logged for admin review

---

### 3.2 Overdue Audit Flagging

**Actor:** System (Automated)

**Trigger:** Daily cron job

**Steps:**

1. Daily cron job runs at 03:00 IST
2. System queries all audits where:
    - Current date > due_date
    - Status ≠ Completed
3. For each overdue audit:
    - Mark is_overdue = true
    - Send escalation notification to TM's SM
    - Add to Red Flags dashboard
4. Weekly (Sunday 04:00 IST):
    - Generate overdue audit report
    - Email to regional managers

**Exit Conditions:**

- Success: Flags set and notifications sent
- Error: Logged for admin review

---

## 4. Mobile App - Outlet Visit Process

### 4.1 Complete Outlet Visit Flow

**Actor:** LSR/TM/SM

**Steps:**

**Phase 1: Pre-Visit**

1. User opens mobile app
2. App loads outlet list with geolocation sorting
3. User views outlets sorted by distance (nearest first)
4. User selects outlet from list
5. User taps "Check In" button

**Phase 2: Check-In**

1. App captures:
    - Check-in timestamp
    - Geolocation coordinates
    - Distance from outlet address
2. App validates geofence:
    - If distance > 100m: Show warning, allow proceed with reason
    - If distance ≤ 100m: Proceed automatically
3. Check-in recorded
4. Outlet detail view displays:
    - Available workflows from assigned template
    - POSM audit status (if applicable)
    - Pending service requests

**Phase 3: Workflow Execution**

1. User selects workflow to execute
2. App loads workflow with outlet-specific customizations
3. User progresses through steps:
    - Step 1: View step details, instructions, sample photo
    - Answer question (Selection or Text Area)
    - Add remarks (if enabled)
    - Capture photos (if required)
    - Tap "Next"
    - System evaluates conditional logic
    - Step 2: (shown if condition met)
    - Repeat until all steps complete
4. Mandatory step validation:
    - If mandatory step not complete: Block submission
    - If skip enabled: Require skip reason
5. User taps "Submit Workflow"
6. App saves workflow execution:
    - If online: Immediate API call
    - If offline: Save locally, sync later
7. System evaluates service request triggers:
    - If trigger condition met: Auto-create service request
    - Send notification to user
8. User can execute additional workflows (repeat Phase 3)

**Phase 4: POSM Audit (if applicable)**

1. User selects "POSM Audit"
2. App displays norms sheet for outlet type
3. User verifies actual quantities per material
4. App auto-calculates variance (actual - norm)
5. User adds remarks for variances
6. User submits audit
7. System triggers next audit task (20 days from today)

**Phase 5: Check-Out**

1. User taps "Check Out" button
2. App captures:
    - Check-out timestamp
    - Auto-calculates time spent (check-out - check-in)
3. User selects visit outcome:
    - Workflows completed
    - Partial completion (with reason)
    - No action taken (with reason)
4. App saves visit log
5. If offline data exists: Prompt to sync

**Exit Conditions:**

- Success: Visit completed and data synced
- Partial: Visit data saved offline, pending sync
- Abandoned: Visit data discarded (if not checked out)

---

## 5. Service Request Lifecycle Process

### 5.1 Service Request Creation & Resolution Flow

**Trigger 1: Automatic (from workflow step)**

**Trigger 2: Manual (user-initiated)**

**Steps:**

**Phase 1: Creation**

1. Service request triggered:
    - Auto: Step response meets trigger condition
    - Manual: User creates from mobile app
2. System applies template:
    - Replace placeholders with actual data
    - Set category, priority, SLA
3. System auto-assigns based on category hierarchy:
    - Equipment Repair → TM
    - Brand Stockout → SM
    - (configurable per category)
4. Service request created with status = Open
5. Notification sent to assigned user
6. SLA countdown starts

**Phase 2: In Progress**

1. Assigned user opens service request in mobile app
2. User taps "Start Work" → Status = In Progress
3. User performs resolution actions (offline)
4. User adds comments to activity log
5. User can reassign to another user (if needed)

**Phase 3: Resolution**

1. User marks issue as fixed
2. User taps "Mark Resolved" → Status = Resolved
3. Notification sent to TM/SM for verification
4. TM/SM reviews:
    - If verified: Tap "Close" → Status = Closed
    - If not verified: Tap "Reopen" → Status = In Progress
5. If SLA exceeded at any point:
    - System flags SLA breach
    - Escalation notification sent
    - Appears in Red Flags dashboard

**Phase 4: Closure**

1. Service request status = Closed
2. Activity log archived
3. Metrics updated (resolution time, SLA compliance)
4. Request removed from active lists

**Alternative: Cancellation**

- At any status: User can cancel with mandatory reason
- Status = Cancelled
- No further action required

---

## 6. Dashboard & Reporting Process

### 6.1 Dashboard Data Flow

**Actor:** Admin/TM/SM

**Steps:**

1. User logs into System Admin
2. Dashboard loads with role-based data:
    - SM: See hierarchy data (all TMs + LSRs)
    - TM: See territory data (own + assigned LSRs)
    - Admin: See all data
3. Dashboard auto-refreshes every 5 minutes
4. User selects date range filter (Today, Last 7 days, Last 30 days, Custom)
5. KPI widgets update:
    - Query: Count outlets visited today where check_in_date = CURRENT_DATE
    - Query: Count workflows completed today with completion rate
    - Query: Count pending service requests with SLA warnings
    - Query: Count overdue POSM audits
6. Visualizations render:
    - Visit Coverage Chart: GROUP BY user/territory
    - Workflow Completion Trend: GROUP BY date
    - Service Request Status: GROUP BY status
    - Brand Availability Score: Calculate % per brand
7. Red Flags section loads with badge counts
8. User clicks widget to drill down
9. System navigates to detailed report with filters preserved
10. User can export snapshot as PDF

**Exit Conditions:**

- Success: Dashboard loaded within 3 seconds
- Error: Show error message, retry option

---

## 7. Offline Data Sync Process

### 7.1 Offline Mode Flow

**Actor:** Mobile App (LSR/TM/SM)

**Scenario:** User loses connectivity during outlet visit

**Steps:**

**Phase 1: Offline Detection**

1. App detects network loss
2. Display persistent banner: "Offline Mode - Data will sync when connected"
3. App switches to offline mode:
    - Use local database (SQLite/Room)
    - Queue all write operations

**Phase 2: Offline Operations**

1. User continues workflow execution
2. App saves all data locally:
    - Workflow responses → local DB
    - Photos → local file storage
    - Visit logs → local DB
3. App assigns temporary IDs (UUID) to all records
4. App marks records as pending_sync = true

**Phase 3: Connectivity Restored**

1. App detects network restored
2. Display sync prompt: "You have offline data. Sync now?"
3. User taps "Sync" (or auto-sync after 30 seconds)

**Phase 4: Data Sync**

1. App calls POST /api/mobile/sync with bulk payload:
    - All pending workflow executions
    - All pending responses
    - All pending visits
2. App uploads photos one by one:
    - POST /api/mobile/files/upload
    - Receive permanent file IDs
3. App updates local records with server IDs
4. App marks records as pending_sync = false
5. Display success message: "All data synced"

**Phase 5: Conflict Resolution** (if any)

1. If sync conflict detected (rare):
    - Server returns conflict error with details
    - App shows conflict resolution UI
    - User resolves manually
2. Retry sync

**Exit Conditions:**

- Success: All offline data synced
- Partial: Some records failed, retry queue maintained
- Error: Display error, allow manual retry

---

## 8. Data Flow Summary

### 8.1 Key Data Flows

**System Admin → Mobile App**

- Workflow configurations
- Outlet assignments
- POSM norms
- Service request assignments
- User permissions

**Mobile App → System Admin**

- Workflow execution data
- Visit logs
- POSM audit results
- Service request updates
- Photos and attachments

**System Admin → System Admin** (Internal)

- Automated audit task generation
- Overdue audit flagging
- Service request auto-assignment
- Dashboard data aggregation
- Report generation

---

## 9. Integration Points

### 9.1 External System Interactions

**Geolocation Service (Google Maps/Mapbox)**

- Distance calculation for outlet sorting
- Geofence validation on check-in
- Address validation on outlet creation

**File Storage (AWS S3/Google Cloud Storage)**

- Photo upload from mobile app
- Photo retrieval for display
- Report export (PDF generation)

**Push Notifications (Firebase Cloud Messaging)**

- Service request assignments
- POSM audit reminders
- SLA breach alerts
- General notifications

**Email Service (SMTP/SendGrid)**

- Weekly overdue audit reports
- SLA breach notifications
- User account notifications

---

## Process Flow Diagrams

*Note: Visual diagrams to be created in design tool (Figma/[Draw.io](http://Draw.io)) and linked here*

### Suggested Diagrams:

1. **Outlet Visit Complete Flow** - Swimlane diagram showing LSR, Mobile App, API, Database interactions
2. **Service Request Lifecycle** - State diagram showing all status transitions
3. **POSM Audit Automation** - Flowchart showing cron job logic
4. **Offline Sync Process** - Sequence diagram showing sync steps
5. **Workflow Execution with Conditional Logic** - Decision tree diagram

---

## Quick Reference - Actor Actions

### System Administrator

- Create/edit workflows
- Create/edit workflow group templates
- Configure outlets
- Assign outlets to users
- Configure POSM norms
- Configure service request categories/templates
- View dashboards and reports
- Manage users

### LSR (Local Sales Representative)

- View assigned outlets
- Check-in/check-out at outlets
- Execute workflows
- Submit workflow responses and photos
- View/update assigned service requests

### TM (Territory Manager)

- All LSR actions
- Execute POSM audits
- Review LSR visits and workflow compliance
- View territory dashboard
- Verify/close service requests

### SM (Sales Manager)

- All TM actions
- View regional dashboard
- Review red flags and escalations
- Export reports

### System (Automated)

- Generate POSM audit tasks (every 20 days)
- Flag overdue audits (daily)
- Auto-assign service requests
- Calculate SLA breach
- Generate weekly reports
- Send notifications

---

**Document Status:** Final

**Next Steps:** Share with development team for reference during implementation