Constrack

## the-problem

## the-approach

• ▸stopped trusting the send: every WhatsApp message is re-fetched from Twilio ten seconds later, and only its *delivered* status counts as sent
• ▸gave failure somewhere to go — an undelivered message is pushed onto the employee's pending queue, TTL-indexed so it expires with the same 24 hours it's waiting on
• ▸made the reply the trigger: an inbound webhook matches the sender's number, flushes every queued message at once and stamps the window open for another day
• ▸and nudged the window open before it was needed — a 20:00 prompt asking for one tap, so the 06:00 task digest lands inside a live session rather than against a closed one
• ▸the digest itself is one aggregation, not a loop: unwind tasks, match today's due dates, group by assignee — one message per person, however many tasks they have
• ▸scoped employees by assignment rather than by flag — their project list is derived from the sub-projects they're on, and a direct hit on a project id is re-checked the same way before anything renders
• ▸derived instead of stored where I could: budget spent is the sum of payments on that project's invoices, and project status is a virtual over the three sub-project buckets — so nothing can drift out of sync with the invoices
• ▸wrote the audit trail from the diff: on save, the modified paths are compared against the pre-save document, so the log says what changed from what to what instead of "project updated"
• ▸a delivery failure is also a visible fact — it lands in the project activity feed as "failed to send to X", so the admin knows a person wasn't told

// Twilio returns a message id, not a delivery. The window may
// have closed hours ago and nothing here would know it, so the
// send is verified after the fact rather than assumed.
client.messages.create({ from: WA_FROM, to, body, mediaUrl })
  .then((res) => setTimeout(() => {
    client.messages(res.sid).fetch().then((message) => {
      if (message.status === "failed" || message.status === "undelivered")
        onFailed?.({ to, body, mediaUrl });   // queue it, don't drop it
    });
  }, 10_000));
 
// …the caller's onFailed parks it on the employee. The TTL is the
// same 24 hours the queue is waiting on: if the window never
// reopens, the backlog expires instead of arriving stale.
pendingNotifications: [{
  to: String, body: String, mediaUrl: [String],
  expiresAt: { type: Date, default: Date.now, expires: 86400 },
}]
 
// One reply — any reply — reopens the window. The webhook flushes
// everything that was held and marks the session live for a day.
export const whatsappReply = async (req, res) => {
  const from = req.body.From.replace("whatsapp:", "");
  // stored numbers vary by how much country code was typed in
  const employee = await Employee.findOne({
    phone: { $in: [from, from.slice(1), from.slice(2), from.slice(3)] },
  });
  if (!employee) return;
 
  employee.notifications.pendingNotifications?.forEach(SendWAMesage);
  employee.notifications.waAllowedTill = moment().add(1, "day").toDate();
  employee.notifications.pendingNotifications = [];
  await employee.save();
};

## the-architecture

## the-results

• ✓the day's tasks reach people who never open the app, and a message that couldn't be delivered is held rather than lost
• ✓an employee's access follows their assignments — nobody maintains a second list of who can see what
• ✓one record answers both questions a contractor asks: how far along is this, and how much of the budget has actually gone out
• ✓shipped and live at constrack.app
• ✓what I'd change: the pending queue is per-employee state mutated from a callback, which is fine on one process and a race on two — it belongs in a small outbox collection with a claim, and the 10-second status check belongs on Twilio's status webhook rather than a timer