Wavu Vendor App – User Guide

1. Getting Started

First Launch

When you open the app for the first time, you will see a passcode screen.

• If you are creating a new business, the default passcode is: admin123
  (You will be asked to change it after your first login.)
• If you are joining an existing business, the owner will give you a passcode (or you'll use the default if you're the owner setting up).

1. Enter the passcode.
2. Tap "Unlock Dashboard Workspace".

If the passcode is correct, you'll be taken to the Dashboard.

Setting Your Recovery PIN (Mandatory First Step)

The first time you log in (after this feature was introduced), you must set a 4‑digit Recovery PIN.

1. You'll see the "Set Your Recovery PIN" screen.
2. Enter a 4‑digit number you can easily remember (e.g., 1234).
3. Confirm it by typing it again.
4. Tap "Set Recovery PIN".

Dashboard Overview

After logging in, you'll see the Dashboard.
This is your main workspace. It shows:

• Two action buttons: Product and Customer – quick links to add new products or customers.
• Search & sort bar for incoming requests.
• A list of incoming live requests – orders sent by customers via SMS or WhatsApp.

From the side menu (three lines top left), you can navigate to other sections:

• Dashboard Hub – back to this screen.
• Sync Queue – view and manage orders waiting to be synced.
• Customer Ledger – manage your customer list and order history.
• Products Management – add, edit, or delete products.
• App Settings Profile – configure your business profile, security, and sync.

2. Handling Incoming Requests

When a customer sends an order via SMS or WhatsApp, it appears as a Request Card on the Dashboard.

Each card shows:

• Customer name (or "M‑PESA" for payment notifications).
• A short summary of the order.
• Status: PENDING, MPESA, or ACCEPTED.

Expand a Request Card

Tap the card to expand it. You will see:

• Full order details.
• Scheduled time and location (if any).
• Charge Amount field – enter the total cost.
• Custom Receipt Notes – add extra notes for the customer.

Actions

When a request is expanded, you have several options:

• Add to Ledger – creates a customer profile (or links to an existing one) and adds the order to the Customer Ledger. The request is marked as accepted.
• Remove – deletes the request permanently.
• Accept – only available for non‑M‑Pesa pending requests. This does the same as "Add to Ledger" and also opens the SMS/WhatsApp app with a pre‑filled confirmation message for the customer.
• Decline – marks the request as declined (removes it from the pending list).

M‑Pesa Requests

• M‑Pesa requests are automatically detected from payment SMS.
• They appear with a green border and a "💰 M‑PESA" label.
• The amount is pre‑filled from the SMS.
• They can only be "Add to Ledger" (Accept is not shown because payment is already confirmed).

3. Products Management

From the side menu, go to Products Management.

Here you can:

• Add a product – tap the floating + button (bottom right).
• Edit a product – tap the yellow edit icon on any product card.
• Delete a product – tap the red delete icon (soft delete; it will be synced to the server).

Each product card shows:

• Product image (if added).
• Product name.
• Price (KES).
• Sync status – "Synced" (green) or "Local Only" (orange).

Add Product Form

When you tap the + button, a bottom sheet opens:

1. Enter Product Name (required).
2. Enter Price (KES).
3. (Optional) Add an image by tapping the camera icon – you can pick from gallery or take a photo.
4. (Optional) Add Custom Attributes – e.g., "Size" → "XL", "Color" → "Red". Tap "Add Attribute" to add more.
5. Tap Save.

The product is saved locally and will be synced to the server on the next sync.

4. Customer Ledger

From the side menu, go to Customer Ledger.

This screen shows a list of all your customers.
Each customer card is expandable to show their order history.

Customer Card

• Collapsed view: shows customer name, phone number, and a total balance indicator.
• Expanded view: shows:
  • Total Balance – calculated from all orders (Paid orders add to balance, Unpaid subtract).
  • Customer Notes – editable notes that apply to the customer. Tap the pencil icon to update notes (changes all orders' notes as well).
  • Order history – each order is displayed as a timeline item with:
    • Order details and timestamp.
    • Payment status – tap "Paid" or "Unpaid" to toggle.
    • Charge Amount – editable field to set invoice amount.
    • Delivery Status – dropdown: Pending / Processing / Complete.
    • Order Notes – specific notes for that order (editable).
    • Delete – removes the order from the ledger.

Adding a Customer

Tap the floating + button (bottom right) to open the "Register New Ledger Profile" sheet.

Fill in:

• Full Customer Name (required).
• Phone Number / Identifier (required).
• What did the customer request? (order details – optional).
• Initial Amount Charged (KES – optional, defaults to 0).
• Account Sub‑notes (optional – e.g., "Prefers delivery after 5pm").

Tap "Save Account".
A new customer and a first order are created, and both are queued for sync.

Searching & Sorting

• Use the search bar at the top to filter by name or phone.
• Tap the sort icon (A‑Z) to switch between:
  • Sort A‑Z – alphabetical order.
  • Sort by Recent Interaction – most recently updated customers first.

5. Sync Queue

From the side menu, go to Sync Queue.

This is your upload/delivery queue for orders that have not yet been sent to the server.
It shows all pending orders waiting for sync.

Queue Card

Each card represents one order and shows:

• Customer name and phone.
• Sync status: "Synced" (green) or "Pending" (orange).
• Amount, Payment, Delivery, Captured (creation time), and Last Updated time.
• The full request and notes.

Actions

• Re‑Sync – force a re‑upload of this order to the server.
• Audit – checks if the order exists on the server.
  • If it exists, the local copy is refreshed with the server version.
  • If it doesn't exist, it is re‑uploaded.
• Remove – deletes the order from the sync queue (does not affect the server).

6. App Settings

From the side menu, go to App Settings Profile.

This is the central place to manage your business profile, security, and sync.

Sections

Business Identity

• Business Shop Name – your store name.
• Contact Phone Number – the business phone.
• Business Email Address – email for communication.

Employee Account

• Your Username (for login) – edit your local display name.
• Web Username (for login) – read‑only name from the server.

Outbound SMS & Messaging Template

• The template that is pre‑filled when you Accept a request.
• A switch to enable/disable sending the confirmation message.

Security Access Management

• Verify Current Passcode – enter your existing passcode.
• New Passcode – change to a new one (must be at least 6 characters).

Pull Latest Profile

• Pull Profile from Server – fetches the latest business profile and logo from the cloud.

Sync Configuration

• Enter your Sync Server URL (e.g., http://192.168.1.100:5001).
• Tap Test to check connection.
• Tap Save URL to store it.

Employee Access

• Business Code – this is your business identifier (owner) or the code to join (employee).
• Master Password – a shared password for employees to join the business.

Recovery PIN

• New 4‑Digit PIN – set or change your recovery PIN.
• Confirm PIN and tap Update Recovery PIN.

Bottom Actions

• Save App Profile Configuration – saves all changes and syncs the profile to the server (if online).
• Create Business / Join Business – appears when you don't have a business set up yet.
• Delete Business / Delete Account – appears if you already have a business.
  • You can choose to delete locally only (reset the app) or delete on the server (permanent).

7. Security & Recovery (Detailed)

Passcode

• Your passcode is the local password you use to unlock the app.
• Default: admin123 (if you haven't changed it).
• Change it in Settings → Security Access Management.

Business Code

• The Business Code is a unique identifier for your business, format WAVU-XXXX-XXXX.
• Owners: It's generated when you create the business. You can copy it from Settings.
• Employees: You receive it from the owner to join the business.

Recovery PIN

• A 4‑digit number you choose.
• Set it the first time you log in (mandatory).
• Update it anytime in Settings → Recovery PIN.

Forgot Your Passcode?

If you forget your passcode:

1. On the login screen, tap "Forgot Passcode?".
2. Enter your Business Code.
3. Tap "Verify & Fallback Passcode".
4. If the business code is correct, a pop‑up will ask for your 4‑digit Recovery PIN.
5. Enter the PIN and tap Verify.
6. If both are correct, your passcode is reset to the default admin123.
7. You will then be forced to set a new passcode immediately.

8. Tips & Troubleshooting

Syncing

• Ensure your Sync Server URL is correct and the server is running.
• Check connectivity with the Test button in Settings.
• The sync queue auto‑processes when you tap Sync Orders or when the app syncs in the background.

Offline Mode

• The app works fully offline for all core features: receiving requests, managing products, customers, and orders.
• Changes are queued and uploaded when you go online.

Role‑Based Views

• Owners see all management options.
• Employees have a limited view (e.g., Business Code and Master Password are read‑only, they cannot delete the business).

Data Backup

• All data is stored locally in a SQLite database.
• If you delete the app, you lose local data. However, if you've synced to the server, your data is safe.

9. Glossary

Term	Description
Business Code	A unique identifier for your business, e.g., WAVU-1234-5678. Used to join and recover.
Recovery PIN	A 4‑digit number you choose; required along with the Business Code to reset a forgotten passcode.
Passcode	Your local login password (min 6 characters).
Sync Queue	A list of orders waiting to be uploaded to the server.
Customer Ledger	The complete list of your customers and their order history.
M‑Pesa	Mobile money payment; detected automatically from SMS.