Hajj and Umrah Software: Hijri Dates and Peak Load

Software that serves Hajj and Umrah has two properties almost nothing else has. Its dates are set by a calendar that is computed for most months and confirmed by observation for the ones that matter most, and its load is not seasonal in the ordinary sense — it is a handful of days a year during which the entire year's demand arrives.

Get either wrong and the failure is not a degraded experience. It is a pilgrim at a gate with a permit your system believes starts tomorrow.

Engineering context. Nusuk, Nusuk Masar and the Ministry of Hajj and Umrah are the authorities on eligibility, contracting and permits.

The calendar is the hard requirement

Saudi Arabia's civil calendar is Umm al-Qura, determined at the Institute of Astronomical and Geophysical Research at King Abdulaziz City for Science and Technology in Riyadh, from modern astronomical theories of the sun and moon.

It is computed, not observed: the length of each of the twelve months is settled by astronomical calculation for a single location, Mecca. Since 1423 AH (15 March 2002) the rule has been that if, on the 29th day of the lunar month, geocentric conjunction occurs before sunset and the moon sets after the sun, the next day begins the new month; otherwise the month runs 30 days.

Then comes the exception that dominates this domain. For three months — Ramadan, Shawwal and Dhul-Hijja — the calendar incorporates actual moon sighting. Dhul-Hijja is the month of Hajj. Shawwal and Ramadan bracket the busiest Umrah period of the year.

So the dates your system cares about most are precisely the ones that are not finally determined by calculation. The sighting usually agrees with the computed calendar and sometimes moves it by a day. Other countries announce months by local sighting, which can fall a day either side of the Saudi determination — which means a pilgrim's home country and their destination can be on different dates simultaneously, and both are correct.

What that means in code

Never hard-code Hijri dates, and never derive them once. A Gregorian date computed at booking and stored as truth will be wrong for some bookings in some years. Store the Hijri date as the authoritative value where the obligation is Hijri, and resolve to Gregorian at the point of use, against the current determination.

Make the calendar a data source, not a library constant. Conversion libraries implement the arithmetic rule. The arithmetic rule is not the whole answer for Dhul-Hijja, Ramadan and Shawwal. Your system needs a place where the confirmed determination is recorded when it is announced, and everything downstream must read from it.

Design for the shift. Ask, for every date-dependent behaviour: what happens if this date moves by one day, four days before it? Permits, transport, accommodation nights, staff rosters, notification schedules and cancellation windows all need an answer. Systems that treat the shift as an exception handle it with a support team and a spreadsheet.

Be explicit about which calendar a date is in, everywhere. In the schema, in the API, in the UI. A field called date in a system spanning two calendars and multiple countries is a defect waiting for a season. And date-only values should stay date-only — a permit is valid on a day, not from an instant, and storing it as a timestamp invites a timezone to shift it.

Assume ambiguity across borders. An agent in Jakarta and an operator in Makkah may be working to different announced dates for the same event. The system should be able to represent that rather than insisting one of them is wrong.

Load arrives all at once

The second structural property: demand is extraordinarily concentrated. Permit windows open and a year's traffic arrives inside minutes. Hajj season compresses the operational year into days.

This is a well-understood engineering problem, but it is worth naming the specific failure modes, because the usual mitigations behave differently at this shape of peak:

Autoscaling is too slow for a window that opens at a known instant. Pre-scale ahead of announced openings; do not rely on reacting.
The database is the bottleneck, not the web tier. Anything that serialises — a booking counter, an allocation table, a sequence — becomes the limit. Queue and allocate asynchronously, and tell the user honestly that they are queued.
Retry storms are self-inflicted. A client that retries aggressively when an endpoint is slow converts a busy system into a failing one. Back off, and make the app's behaviour under load a deliberate design decision.
Fairness is a product requirement. When demand exceeds supply for something people have saved years for, "whoever had the fastest connection" is not an acceptable allocation policy. Decide the policy deliberately and be able to explain it.

Off-season, the same system is nearly idle. Architect for the ratio — this is a strong case for elastic infrastructure and for keeping the expensive, hard-to-scale components as small as possible.

The platform layer: Nusuk and Nusuk Masar

Nusuk is the pilgrim-facing platform for Hajj and Umrah, with dedicated portals and an app carrying a large catalogue of digital services — reported figures vary by source and date, in the range of 100 or more services and tens of millions of users.

Nusuk Masar was launched by the Ministry of Hajj and Umrah at the Digital Government Forum in 2024. It unifies contracting procedures, operational and field activity, and visa processing in one digital infrastructure, covering permits, bookings and guidance programmes. It carries external-agent qualification and final contracting — for the 1448 AH Umrah season, for instance — and lets Saudi Umrah companies contract with domestic service providers for accommodation, transport, catering and packages.

The integration reality is the same as elsewhere in Saudi government technology, and it should be said plainly: this is a qualified and contracted participant model, not an open developer platform. Access follows from being an approved agent or service provider, through the Ministry's processes. It is not a signup. Plan it as a dependency with its own timeline, exactly as with other Saudi government platform integrations.

For most software companies the honest scoping is: you are building the operator's system — the agency, the transport company, the accommodation provider — and it interoperates with the official platforms where the operator's own qualification permits. That is substantial, real work, and it is a different project from "integrating with Nusuk".

The rest of the requirements list

Language is not a feature here. Pilgrims arrive from everywhere. Arabic, English, Urdu, Bahasa Indonesia, Malay, Turkish, French, Hausa — with right-to-left rendering done properly, not as a stylesheet flip. Names will not fit Latin-alphabet assumptions.

Assume a mid-range Android phone on a congested network. During peak, hundreds of thousands of devices share the same cells in a small area. Payload size, offline tolerance and graceful degradation are functional requirements, not optimisations. A pilgrim who cannot load their permit because the venue's connectivity is saturated has been failed by the software, not the network.

Accessibility is unusually load-bearing. The pilgrim population includes many elderly users and users with limited mobility or vision, often using a phone in bright sunlight while tired. Large targets, high contrast and short flows are the baseline.

Group and family structures are the norm, not the exception. People travel in groups, and one person routinely acts for several. Model that in the domain rather than bolting delegation onto a single-user account, because the workaround — sharing logins — is what happens otherwise.

Payments span currencies and methods. Pilgrims pay from their home country in their own currency and context; operators settle locally. Our guide to mada, STC Pay, Apple Pay and BNPL covers the Saudi side.

And the obligations do not pause for the season. An operator issuing invoices in Saudi Arabia is in the e-invoicing regime like anyone else — Wave 25 closes on 1 February 2027. Personal data is governed by PDPL, and where it is hosted by CST's cloud rules.

Jeddah is the practical centre of much of this — the arrival point for a large share of pilgrims and the base for many of the operators, logistics businesses and service providers whose systems this describes. See app development in Jeddah.

Frequently asked questions

Which calendar does Saudi Arabia use officially?

Umm al-Qura, determined at KACST's Institute of Astronomical and Geophysical Research in Riyadh from astronomical calculation for Mecca.

If it is calculated, why do dates still move?

Because for Ramadan, Shawwal and Dhul-Hijja the calendar incorporates actual moon sighting. Dhul-Hijja is the month of Hajj, so Hajj dates are among those that can shift.

How far can a date move?

Typically by a single day relative to the calculated calendar. Other countries announcing by local sighting can be a day either side of the Saudi determination.

Can I just use a Hijri conversion library?

For ordinary months, yes. For Ramadan, Shawwal and Dhul-Hijja a library implements the arithmetic rule, not the confirmed sighting. Record the announced determination and read from it.

What is the difference between Nusuk and Nusuk Masar?

Nusuk is the pilgrim-facing platform. Nusuk Masar, launched in 2024, is the ministry platform unifying contracting, operations and visa processing for companies and agents.

Can I integrate with Nusuk as a software vendor?

Not by signing up. Access follows from qualified or contracted status through the Ministry of Hajj and Umrah's processes. Most vendors build the operator's system instead.

What is the single biggest architectural risk?

Concentrated load at a known instant. Pre-scale, queue and allocate asynchronously, and decide your fairness policy deliberately.

Does an Umrah operator have e-invoicing obligations?

If it is a VAT-registered taxpayer in scope, yes — the same ZATCA regime as any other business.

Building Hajj and Umrah software: the Hijri calendar problem and load that arrives all at once