A Business-Calendar Service for Indian Automation Flows: Working Hours, Holidays and Regional Festivals

#architecture #automation #india #python

Disclosure: I co-founded NxFlowAI, a Mumbai-based AI automation agency. The pattern below is generic and is not a product pitch.

Automations that send reminders, escalate unanswered leads or promise "we will reply by tomorrow" all depend on one thing: knowing when the business is actually open. In India that is harder than it looks. Working days differ by business, weekly offs differ by city, and festivals differ by state and community. Any AI automation agency India SMEs rely on for reminders needs a calendar layer instead of hard-coded hours.

The problem with hard-coded hours

The usual first version is if 10 <= hour < 19 and weekday < 6. It breaks immediately:

A shop in one city closes on Monday; a clinic elsewhere closes on Thursday afternoon.
Diwali, Eid, Onam, Pongal, Durga Puja and Ganeshotsav each matter to different businesses in different regions.
Owners close unexpectedly for a family function and tell customers on WhatsApp, not in any system.

When the code does not know about these, customers get "we will call you in an hour" at 9 pm on a festival night.

A tiny calendar service

Keep one small service that answers three questions:

is_open(business_id, datetime)
next_open(business_id, datetime)
add_business_minutes(business_id, datetime, minutes)

Every flow calls it instead of checking hours itself.

business: example-store
timezone: Asia/Kolkata
weekly:
  mon: closed
  tue-sat: "10:30-20:00"
  sun: "11:00-14:00"
holidays:
  source: owner_list   # owner picks from a regional list, then edits
  dates: []
ad_hoc_closures:
  - {date: null, reason: null}   # set from a WhatsApp command by the owner

Let the owner close the shop from WhatsApp

The most useful feature is a single command the owner can send, such as "CLOSED TODAY". The service records an ad-hoc closure, and every pending reminder shifts to the next open slot. Without this, the calendar goes stale within a month.

Regional festival lists as suggestions, not truth

Ship a starting list per state, but make the owner confirm it. A jeweller and a hardware store on the same street may treat the same festival very differently: one is at peak, one is shut.

Use business minutes for promises

If a flow promises "reply within 2 business hours", compute the deadline with add_business_minutes. Escalations then fire at a sensible time, not at midnight.

Test with ugly dates

Write tests for the day before a long weekend, a closure announced at 9 am, and a reminder scheduled across a festival. These are where real complaints come from.

Where this fits

Calendar logic is unglamorous, but it decides whether automation feels polite or robotic. If you are mapping which of your flows depend on timing, list them before you build. A 72-hour workflow audit is one way to do that.

Disclosure again: I co-founded NxFlowAI. The pattern above is generic and works with any stack.

DEV Community