📋 1. What this tool is and how it's structured

This is a shared cloud-based operations hub for your client services team. It has two distinct purposes that deliberately live in the same place:

• External reporting — generating the WhatsApp message you send to management daily
• Internal tracking — monitoring your team's time, tasks, projects, billing and performance

The tool has 8 modules:

• Daily Entry — each person fills their own numbers every day
• WhatsApp Report — auto-generated consolidated message, copy-paste ready
• Team Dashboard — your internal view of everyone's activity, filterable by date
• Insights — auto-generated flags, risks and observations based on the data
• Projects & POs — project registry with PO details, timelines, and planned billing schedules
• Invoices — actual invoices raised against each project
• Billing Tracker — planned vs actual billing per project per month with deviation and reasons
• Settings — manage team member names and roles

👥 2. Roles and who sees what

There are three roles. Everyone opens the same tool — there is no separate login or separate link. Role differences are about intent and responsibility, not technical access restriction.

Visibility matrix

🔄 3. Sync, storage and the shared cloud — your biggest concern

How data is stored

There are 4 KV keys — think of them as 4 tables:

What happens when two people save at the same time

This is the most important thing to understand. The storage system uses last-write-wins. Here's what that means in practice:

• Person A opens the tool and starts filling their entry at 9:00 AM
• Person B opens the tool and saves their entry at 9:05 AM — this writes the full ops_v5_shared object to the cloud
• Person A saves at 9:07 AM — this also writes the full object, but only contains what was in their browser when they loaded the page
• Risk: If Person A's browser loaded before Person B saved, Person A's save will overwrite and lose Person B's entry

How to recover if data is overwritten

• The tool does not have version history — once overwritten, the previous save is gone from the cloud
• Best practice: if you suspect a conflict, the manager should re-enter the missing person's data manually from their WhatsApp report or verbal update
• A future improvement could be to save each person's entry as a separate key (e.g. daily_2026-05-29_Manisha) to fully eliminate conflicts — this is the safest architecture change if conflicts become a real problem

How refresh works — background sync

The tool now syncs automatically in the background every 90 seconds. You can see the sync status in the bottom of the sidebar — it shows either "⟳ Syncing…", "✓ Synced HH:MM", or "⚠ Sync failed".

Here is exactly what happens on each background sync cycle:

• All four data stores (daily entries, members, projects, invoices) are re-fetched from the cloud
• The fetched data is compared to what's currently in memory
• If data has changed — the current tab re-renders automatically and silently. No page reload, no lost work
• If data hasn't changed — nothing happens, no visual disruption
• The member dropdown in Daily Entry is also refreshed so new names appear without a page reload

The concurrent save risk — still relevant

Background sync reduces the window of risk significantly but does not fully eliminate the concurrent save problem. Here's the updated picture:

• Every 90 seconds, everyone's browser pulls the latest state from the cloud
• If two people happen to click Save within the same 90-second window and both have stale data, the last save still wins
• In practice this window is very narrow — the team fills entries at different times of day
• The safest behaviour remains: open → fill → save promptly, not open early and save hours later

What is and isn't saved automatically

📅 4. Daily workflow — step by step

Morning routine (team members + coordinator)

End of day routine (Manisha)

Project / billing routine (Manisha + Coordinator)

🔢 5. All calculation logic explained

Utilisation

MTD / QTD / YTD

WhatsApp report — what's included vs reference-only

Invoice date deviation

Monthly billing deviation

PO utilisation

Project timeline deviation

📁 6. Projects, POs and billing schedules

What each field means

• Project name — free text, used everywhere as the display label
• Client / Company — the pharma company this project is for
• Assigned to — one person owns this project; their name appears in team task breakdowns
• Category — what type of work this project represents (active delivery, renewal, new biz, etc.)
• PO Number — the client's purchase order reference
• PO Value — the total contracted value in ₹Cr. This is the ceiling for fixed-price projects
• Start / Estimated end dates — the agreed project timeline
• Actual end date — fill this only when the project is truly complete. Leave blank if ongoing
• PO deviation reason — why the project timeline or PO scope changed from original. This is project-level, not invoice-level
• Planned monthly billing schedule — month by month, how much you planned to invoice. This is the baseline against which actuals are compared

How tasks connect to projects

When a team member logs a task in Daily Entry, they can tag it to a project from the dropdown. This project dropdown is populated from whatever projects exist in the Projects & POs tab. If a project isn't set up yet, tasks will show as "No project" in the team dashboard.

🧾 7. Invoices and deviation tracking

Invoice fields

• Project — which project this invoice belongs to. Required for billing tracker to work
• Invoice number — your internal or client-facing invoice reference
• Invoice value — in ₹Cr
• Actual raise date — the date the invoice was actually raised
• Planned raise date — the date you originally planned to raise it (from the billing schedule). Used to calculate date deviation
• Deviation reason — why actual date differs from planned. Options: Scope change, Client delay, Delivery delay (our side), Payment hold by client, PO amendment, Other
• Deviation notes — free text to give more detail on the reason
• Status — Raised / Submitted / Paid / Overdue

How deviation reasons flow to the Billing Tracker

The Billing Tracker groups invoices by the month of their actual raise date. For each month, it collects all unique deviation reasons from invoices in that month and displays them in the Reason column. So if two invoices in March both had "Client delay", it shows "Client delay" once.

⚡ 8. How auto-insights are generated

Insights are computed fresh every time you open the Insights tab or change the date range. They are not stored — they're generated from the live data. Here is every rule the system checks:

Utilisation flags

Time drain flags

Project health flags

Billing flags

Task flags

Positive signals

🛠 9. How to think about future changes

When you want to modify how the tool works, here are the key things to think about:

Adding a new field to daily entry

• Add the input in the Entry tab HTML
• Add the field to defEntry() with a default value
• Add it to the loadEntry() function to populate on load
• Add it to saveEntry() to collect and save it
• If it should appear in the WhatsApp report, add it to renderReport()
• If it should appear in insights, add logic to renderInsights()

Changing the utilisation target (currently 8.5h)

• Find the constant const TARGET=8.5 near the top of the script and change the value
• This flows automatically to utilisation %, colour coding, and insights

Adding a new deviation reason category

• Find the <select> dropdowns for deviation reasons in both the project modal and invoice modal
• Add a new <option> to each

Changing what's copied to WhatsApp vs reference-only

• In renderReport(), the copyText variable is what gets copied
• The refText variable is the reference section
• Move lines between the two variables to change what's included in the copy

Fixing the concurrent save conflict (most important future improvement)

Currently all daily entries are stored in one shared object. The safest fix is to change the storage key to be per-person per-day, e.g. daily_2026-05-29_Manisha. This means each person's save is completely independent and cannot overwrite anyone else's. The trade-off is slightly more storage reads when consolidating — but fully eliminates conflicts.

Adding a new project category

• Find the CATS array in the script — add your new category string there
• Also add it to the <select> in the project modal

❓ 10. Common questions

Someone forgot to submit today — can I fill it for them?

Yes. Go to Daily Entry, select their name from the dropdown, pick the date, fill in their numbers and save. The data will be stored under their name for that date.

Can someone edit a past day's entry?

Yes. Go to Daily Entry, select their name, change the date to the past date, make edits, and save. It will overwrite whatever was previously saved for that person on that date.

Can a team member see what their colleagues entered?

Not directly from their own entry form — they only see their own fields. But if they navigate to the Team Dashboard tab, they can see everyone's data. There is no technical restriction preventing this.

What happens if I rename a team member in Settings?

Their past daily entries will be orphaned — the entries are stored under the old name and won't link to the new name. Do not rename members once they've started submitting data. If a name is misspelled, fix it before the first entry is saved.

The Billing Tracker shows zero for a month even though I raised an invoice

Check that the invoice's project is correctly set, and that the invoice date falls in the month you're expecting. The tracker uses the actual raise date (not the planned date) to determine which month an invoice belongs to.

Insights are blank / not showing anything

Insights are generated from the date range set at the top of the Insights tab. If the range has no daily entries, no insights will generate. Make sure the date range covers days where entries have been saved.

How do I export all data for backup?

Go to Settings → click "Export all data (JSON)". This downloads a JSON file with all four data stores. Keep this as a backup — if the cloud storage is ever cleared, this file can be used to restore data (requires manual re-import currently).