Calendars module (calendars)

The calendars module in src/cluster_erp/modules/calendars/ holds working time. It keeps shifts, weekly working-time templates, and working calendars that an owner such as a party, a work center, or the company group can own. A calendar has a time zone, a template, an optional base calendar it inherits from, and date exceptions such as holidays. Other modules read effective working days and windows from it through the EventBus; the time math is on working time.

At a glance¶

What the module does¶

• Keeps named shifts and weekly templates of per-weekday spans; several lines per day are split shifts, and an end at or before the start crosses midnight (src/cluster_erp/modules/calendars/models.py:1-14).
• Keeps working calendars with a time zone, a template, an optional base calendar, and an optional owner (src/cluster_erp/modules/calendars/models.py:119-180).
• Keeps date exceptions with a one-off, annual, or weekly recurrence, an open, closed, or inherit control, and optional custom hours (src/cluster_erp/modules/calendars/models.py:183-233).
• Imports public holidays of a country into a calendar with the holidays library (src/cluster_erp/modules/calendars/services.py:455-516).
• Answers queries for owner working days, effective calendars, and day windows (src/cluster_erp/modules/calendars/module.py:51-63).

Sub-modules¶

The router is mounted under the module prefix with require_app("calendars") (src/cluster_erp/modules/calendars/module.py:33-41).

Data model¶

The owner is stored on the calendar, not on the owner's table, so that no module has to depend on calendars (src/cluster_erp/modules/calendars/models.py:163-168). Template and exception times are wall-clock times in the calendar's time zone (src/cluster_erp/modules/calendars/models.py:141-148).

Screens and metadata¶

get_metadata declares a sidebar group Calendars (Turkish Takvimler) with one custom section, Global Calendar (global_calendar) (src/cluster_erp/modules/calendars/module.py:204-219). The web widget overlays every working calendar on one month grid from the preview route (gated_apps/calendars/app.js:1-6). See gated app bundles and desktop module screens.

Status and actions¶

Calendars have no status and no ActionMeta. Records are changed through the routes listed under Permissions.

Business rules¶

• The company group calendar is a singleton owned by ("group", nil id); GET /group creates it when missing. Organisations use it as their base to inherit group holidays (src/cluster_erp/modules/calendars/routes.py:74-94, src/cluster_erp/modules/calendars/services.py:224-312).
• POST /calendars/for-owner gets or creates the calendar of an owner. With inherit_from, the new calendar copies the parent's template and time zone and uses it as base; otherwise it gets its own Monday to Friday 08:00 to 17:00 template (src/cluster_erp/modules/calendars/services.py:224-312).
• A base calendar chain may not form a cycle (src/cluster_erp/modules/calendars/services.py:363-386).
• An exception's recurrence and control are validated against the engine enums (src/cluster_erp/modules/calendars/schemas.py:192-205, src/cluster_erp/modules/calendars/services.py:631-646).
• GET /calendars/{calendar_id}/preview returns the resolved days with shifts, exceptions, and holidays applied (src/cluster_erp/modules/calendars/routes.py:296-335, src/cluster_erp/modules/calendars/services.py:439-454).
• Changes that affect effective hours emit WorkingCalendarChanged for each affected calendar, with its owner (src/cluster_erp/modules/calendars/routes.py:47-66).

Events and queries¶

The module consumes 4 contracts and produces 1, counted as on the parties module page. The full list is on the contracts reference.

Consumers include MRP lead times, the scheduling board, the project board, and the sales order delivery date check; see material requirements planning, production scheduling, and project board.

Permissions¶

Privacy, retention, and history¶

The module has no privacy_handlers.py. Deletes set deleted_at (src/cluster_erp/modules/calendars/services.py:77-88). Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

Supported holiday countries come from the holidays library and are listed by GET /holiday-countries (src/cluster_erp/modules/calendars/services.py:510-516, src/cluster_erp/modules/calendars/routes.py:95).

Tests¶

Found by a grep for modules.calendars in tests/ and by file name and the path /calendars/ in web-client/.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Working time
• Production scheduling
• Material requirements planning
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.