Personal Shift Planner: rotating work shifts in the household calendar

[ulsklyc]

Moved here from issue #661 so that feature ideas live where the rest of the backlog is discussed. Originally proposed by @mclgoerg - the full proposal, including the detailed data model and UI sketch, is in #661.

The idea. A Personal Shift Planner module where household members manage their own recurring work schedules, optionally shown in the calendar. Explicitly not workforce scheduling: the goal is helping a family coordinate everyday life around personal shifts.

Why. Many households include people working rotating or irregular shifts - healthcare, emergency services, retail, hospitality, manufacturing, logistics. Knowing who is working when makes family activities, appointments, childcare and household tasks much easier to plan.

Related but not the same: #749 (Weekly Timetable) covers a fixed weekly schedule rather than rotating shift patterns. Worth deciding whether these are one module or two.

Open questions from my side: whether shifts should be their own module or a shift-pattern layer on top of the calendar, and how far the recurrence needs to go beyond what the calendar's recurrence rules already do.

[mclgoerg]

Thanks for moving this over!

I agree that #749 and this proposal are closely related. A fixed weekly timetable and a rotating shift schedule could probably share the same underlying schedule/pattern concept rather than being implemented as two completely independent features.

My preference would be to keep the schedule/pattern data separate from normal calendar events and expose it as an optional calendar overlay. The calendar would visualize the resulting schedule, but wouldn’t necessarily need to own all of the shift/pattern-specific logic.

Conceptually, I could imagine a more general Personal Schedule supporting different kinds of patterns:

• Fixed weekly patterns - e.g. school/university timetable or regular working hours
• Rotating patterns - e.g. Early → Early → Late → Late → Night → Night → Off → Off, repeating independently of calendar weeks
• Individual entries / overrides – e.g. a different shift on one particular day, vacation, training, etc.

Both fixed and rotating schedules could then optionally be shown in the existing calendar and toggled on/off there.

Regarding recurrence, I think this is where shift patterns differ somewhat from normal calendar recurrence. A calendar rule works very well for things like “every Monday at 08:00”, but many shift systems are based on a continuously rotating cycle rather than weekdays. For example:

Early → Early → Late → Late → Night → Night → Off → Off → repeat

The next occurrence is determined by the position in the cycle, not by the day of the week. Ideally a user could define such a pattern once, choose a starting date, and have it continue from there.

I would still keep context-specific functionality separate. Things such as worked-hours statistics, night/weekend/public-holiday allowances, etc. make sense for a work schedule but probably shouldn’t complicate a basic school timetable.

So personally I would lean towards one underlying schedule/pattern system shared with #749, with optional calendar integration, rather than modelling every shift directly as an ordinary calendar event.

That would also leave room for some of the optional ideas from #661 later, such as importing a shift plan from a PDF/screenshot or creating a pattern from natural-language input, without making any of that a requirement for the initial implementation.

[mclgoerg]

One additional thought regarding recurrence: I think this is probably one of the areas where the shift planner would need to go beyond the calendar’s existing recurrence rules.

Real-world shift systems can vary quite a lot, so ideally the implementation shouldn’t have hard-coded concepts such as “4 on / 2 off”, “every second weekend”, etc. Instead, I think a generic cycle-based pattern model could cover most use cases.

For example, a pattern could essentially consist of:

• a start/anchor date
• an arbitrary cycle length
• an ordered list of entries within that cycle
• each entry referencing a reusable shift type or representing an off/free day

A simple 8-day rotation could then look like this:

Pattern: Regular rotation
Anchor date: 2026-09-01
Cycle length: 8 days
Day 1: Early   06:00–14:00
Day 2: Early   06:00–14:00
Day 3: Late    14:00–22:00
Day 4: Late    14:00–22:00
Day 5: Night   22:00–06:00
Day 6: Night   22:00–06:00
Day 7: Off
Day 8: Off

Or, more simply:

Early → Early → Late → Late → Night → Night → Off → Off → repeat

The important difference to normal calendar recurrence is that it is not necessarily the same event repeating. It is a sequence of different entries repeating as one cycle and that cycle may be completely independent of weekdays or calendar weeks.

Recurrence / pattern capabilities

I think the underlying model should ideally be flexible enough to support:

• Arbitrary cycle lengths (e.g. 3, 7, 8, 10, 14, 28 days…)
• Cycles starting on any date, not necessarily Monday
• Different shift types within the same cycle
• Different start/end times per shift type
• Shifts crossing midnight
• Explicit off/free days
• Fixed weekly schedules
• Multi-week schedules (e.g. Week A / Week B)
• Finite patterns with an optional end date
• Patterns continuing indefinitely
• Changing to a new pattern from a specific date onward
• Individual overrides/exceptions without modifying the base pattern

The last two points might be especially important from a data-model perspective.

Pattern history / effective dates

For example, somebody might work Pattern A from January to June and switch to Pattern B on July 1st.

Changing the active pattern shouldn’t retroactively change their historical schedule.

Conceptually, pattern assignments could therefore have something like:

Pattern: Rotation A
Member: Alice
valid_from: 2026-01-01
valid_until: 2026-06-30
Pattern: Rotation B
Member: Alice
valid_from: 2026-07-01
valid_until: null

This would preserve historical schedules while still allowing future schedules to change.

Overrides / exceptions

Individual occurrences should probably also be overridable without modifying or breaking the underlying rotation.

For example:

Base pattern:
2026-06-10 → Early (06:00–14:00)
Override:
2026-06-10 → Vacation

Other examples could be:

Base pattern:
2026-06-15 → Night (22:00–06:00)
Override:
2026-06-15 → Late (14:00–22:00)

or simply:

Base pattern:
2026-06-20 → Early
Override:
2026-06-20 → Off

This could be useful for vacation, sickness, training, shift swaps, overtime or just one-off deviations from the normal rotation.

Possible data model

That might suggest separating the concepts into roughly four layers:

Shift Types
    ↓
Patterns
    ↓
Pattern Assignments
    ↓
Overrides / Exceptions

1. Shift Types

Reusable definitions such as:

Early
06:00–14:00
Late
14:00–22:00
Night
22:00–06:00
24h
08:00–08:00

These could contain the name, color, icon and default start/end times.

2. Patterns

Define the actual sequence:

Day 1 → Early
Day 2 → Early
Day 3 → Late
Day 4 → Late
Day 5 → Night
Day 6 → Night
Day 7 → Off
Day 8 → Off

3. Pattern Assignments

Connect a pattern to a household member and a time period:

Member: Alice
Pattern: Regular rotation
Anchor date: 2026-09-01
Valid until: indefinite

4. Overrides / Exceptions

Modify individual occurrences without touching the underlying pattern:

2026-09-17
Original: Night
Override: Vacation

Calculating occurrences instead of generating events

The calendar could then resolve occurrences for the requested date range rather than necessarily storing thousands of generated calendar events.

For an 8-day cycle, the pattern position for a given date can conceptually be derived from:

daysSinceAnchor % cycleLength

For example:

Anchor:       2026-09-01
Cycle length: 8
2026-09-01 → position 0 → Early
2026-09-02 → position 1 → Early
2026-09-03 → position 2 → Late
...
2026-09-08 → position 7 → Off
2026-09-09 → position 0 → Early

Overrides could then be applied on top of the resolved occurrence.

That would avoid having to generate years of future calendar events just because somebody has an indefinite shift rotation.

The calendar integration could effectively behave like an overlay/view of the schedule data, which could then be enabled or disabled independently.

Relation to #749

I think #749 could potentially use exactly the same underlying pattern system.

A fixed weekly timetable is essentially a 7-day pattern anchored to weekdays:

Monday    → School 08:00–15:00
Tuesday   → School 08:00–15:00
Wednesday → School 08:00–13:00
Thursday  → School 08:00–15:00
Friday    → School 08:00–13:00
Saturday  → Off
Sunday    → Off

A rotating shift schedule would simply be the more general case where the cycle length and anchor aren’t necessarily tied to a calendar week.

A two-week timetable would similarly just be a 14-day pattern.

So the underlying concept could potentially be shared without forcing the UI or functionality to be identical.

Edge cases

There are also some edge cases worth keeping in mind, even if they aren’t all part of an initial implementation:

• Daylight-saving time changes
• Overnight shifts where the end date differs from the start date
• Shifts longer than 24 hours
• Pattern changes
• Temporary deviations from a pattern
• Vacation / sickness / training replacing a scheduled shift
• Timezone handling
• Overlapping entries
• Multiple entries on the same day

Keeping the underlying occurrences structured would also be useful if the optional statistics/allowances from #661 are ever implemented later.

For example, it could eventually allow calculations such as:

June 2026
Worked:              162.5 h
Night hours:           38.0 h
Sunday hours:          16.0 h
Public holiday hours:   8.0 h
Early shifts:  7
Late shifts:   6
Night shifts:  5

and potentially calculate configurable allowances based on those hours.

So overall, I would favor a fairly generic cycle + assignment + exception model rather than extending the calendar recurrence rules with lots of shift-specific recurrence types.

The UI could still provide convenient presets such as:

• Weekly
• Every second week
• 4 on / 2 off
• 24h on / 48h off
• Custom rotation

but those could all map to the same generic pattern model underneath.

That would keep the common cases easy to configure while still being flexible enough for the many different shift systems people actually work.

[mclgoerg]

@ulsklyc Are there any plans to add this feature? I could also work on it and create a PR.

[ulsklyc]

Yes - and thank you for the offer. Before you write any code, though, the decision that has been sitting on my side needs making, because leaving an architectural question with a contributor is a mistake I have made once in this repository and I am not repeating it.

Three decisions, and they are mine rather than yours:

1. One model, not two. You and Benoit in #749 are describing the same thing. A "Week A / Week B" school timetable is a 14-day cycle anchored to a date; your Early-Early-Late-Late-Night-Night-Off-Off is an 8-day one. Building the fixed weekly timetable as its own feature would mean implementing the same arithmetic a second time six months later. Your generic cycle model covers both, and that is what goes in.

2. A pattern, not calendar recurrence. Worth being precise about why, because the calendar could technically do it: six FREQ=DAILY;INTERVAL=8 series with different anchor dates reproduce your rotation exactly. It works and it reads terribly - you would maintain six unrelated series to express one pattern, and changing the cycle means editing all six consistently. The deeper reason is that a rotation is a sequence of different entries repeating as one unit, which is not what an RRULE describes. Your model is the right one.

3. An overlay, not materialised events. Your preference matches mine, with a second argument for it: a rotation running two years is roughly 700 rows per person if every day becomes an event, and each pattern edit then has to reconcile them. Computed from anchor date plus cycle position it is one row for the pattern plus one per override. The calendar renders it and does not own it.

Three things I would still like your view on, since you are the one living with this:

• Overrides. A swapped shift, a holiday, a training day. Does an override replace that day's entry or sit alongside it - and when you swap with a colleague, is that one override or two?
• What the rest of the household needs. Is the useful thing a full shift block in the calendar, or something quieter? My instinct is that the family mostly needs to know that Anna is unavailable on Tuesday evening, and that her exact 14:00-22:00 matters more to Anna than to them.
• Where the first version stops. I would take fixed weekly patterns, rotating cycles and per-day overrides, and leave out shift swapping between members, time-off requests and anything else that starts to look like workforce management.

If that shape works for you, the PR is welcome. I will write the data model up here first - patterns, shift types and overrides - so you are not guessing at table layouts, and it lands as a module that ships switched off, the way Inventory does. Say so and I will post the spec next.

[ulsklyc]

As promised, the data model. Long post, but it is the thing that lets you start without guessing, and everything below is a decision rather than an option.

Name and scope

The module is schedule, not shifts. It carries both this thread and Benoit's timetable in #749, and a name that only mentions shifts would make the timetable case a guest in its own module. One module, one name.

Four tables, three concepts

I said three in my last comment. It is four, because the cycle is an ordered list and that is a table of its own rather than a JSON column - the cycle needs to be queried, and a JSON blob is the kind of second format that stops being readable the moment something has to reconcile it.

All of this goes in as migration 160 (159 is the highest today). Migrations are append-only in server/db.js: add to the end of the MIGRATIONS array, never edit or reorder an existing entry.

-- A reusable shift type. Household-wide, because two people on the same ward
-- share the same "Early". Times are wall-clock strings, never instants.
CREATE TABLE IF NOT EXISTS schedule_shift_types (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  name       TEXT    NOT NULL,
  short_code TEXT,                      -- "E", "N" - what fits in a calendar cell
  start_time TEXT,                      -- 'HH:MM', NULL for all-day (vacation, training)
  end_time   TEXT,                      -- 'HH:MM'; < start_time means it ends next day
  color      TEXT    NOT NULL DEFAULT '#6C3AED',
  created_by INTEGER REFERENCES users(id) ON DELETE SET NULL,
  created_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
  updated_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
  CHECK ((start_time IS NULL) = (end_time IS NULL))
);

-- One pattern per person per purpose. "My rotation", "School timetable".
CREATE TABLE IF NOT EXISTS schedule_patterns (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id      INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  name         TEXT    NOT NULL,
  anchor_date  TEXT    NOT NULL,        -- 'YYYY-MM-DD', day 1 of the cycle
  cycle_length INTEGER NOT NULL CHECK (cycle_length BETWEEN 1 AND 366),
  valid_from   TEXT,                    -- NULL = open at that end
  valid_until  TEXT,
  is_active    INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0, 1)),
  created_at   TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
  updated_at   TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
);

-- Position within the cycle. A missing row, or a NULL shift type, is a free day.
CREATE TABLE IF NOT EXISTS schedule_pattern_days (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  pattern_id    INTEGER NOT NULL REFERENCES schedule_patterns(id) ON DELETE CASCADE,
  position      INTEGER NOT NULL CHECK (position >= 0),   -- 0-based, < cycle_length
  shift_type_id INTEGER REFERENCES schedule_shift_types(id) ON DELETE RESTRICT,
  UNIQUE (pattern_id, position)
);

-- One calendar day that deviates. The row's existence IS the override.
CREATE TABLE IF NOT EXISTS schedule_overrides (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  date_key      TEXT    NOT NULL,       -- 'YYYY-MM-DD'
  shift_type_id INTEGER REFERENCES schedule_shift_types(id) ON DELETE RESTRICT,
  note          TEXT,
  created_at    TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
  UNIQUE (user_id, date_key)
);

CREATE INDEX IF NOT EXISTS idx_schedule_patterns_user   ON schedule_patterns(user_id);
CREATE INDEX IF NOT EXISTS idx_schedule_overrides_user  ON schedule_overrides(user_id, date_key);

Plus the trg_<table>_updated_at triggers on the two tables that carry updated_at, in the same shape as the rest of the schema.

The decisions inside that DDL

A free day is shift_type_id IS NULL, not a special "Off" type. Your model said "referencing a reusable shift type or representing an off/free day", and NULL expresses exactly that without a magic row that could be renamed or deleted.

An override is its row. No is_deleted flag, no tri-state. Row present with a type: that day is that shift. Row present with NULL: that day is free. No row: the pattern decides. This also answers your first question - an override replaces the day, it does not sit alongside it. A swap with a colleague is therefore two overrides if both people are in the household, one if the colleague is not, and that asymmetry is correct: Yuvomi only knows about your household.

Vacation and training are shift types, not a fourth concept. They are all-day (start_time IS NULL) and they land in overrides like anything else. That is why the CHECK ties the two times together rather than allowing a half-specified one.

ON DELETE RESTRICT on both shift-type references. Deleting a type that is in use must fail loudly. SET NULL would silently turn every night shift in someone's rotation into a free day, and they would find out by not showing up.

The arithmetic, and the trap in it

Position in the cycle for a given day:

const days = daysBetween(pattern.anchor_date, dateKey);
const position = ((days % pattern.cycle_length) + pattern.cycle_length) % pattern.cycle_length;

The double modulo is not decoration. Days before the anchor date are negative, and JavaScript's % keeps the sign, so a single % puts a date before the anchor at a negative position and it silently matches nothing.

daysBetween must count calendar days, not milliseconds. Dividing a millisecond difference by 86400000 is wrong twice a year: across a DST boundary that day is 23 or 25 hours long, and a rotation would slip by one position and stay wrong. server/utils/timezone.js already has shiftDateKey(dateKey, days) for exactly this, and the counterpart belongs next to it.

Two more rules from this codebase that a new module gets wrong by default:

• Never build a date key with .toISOString().slice(0, 10). West of UTC it returns yesterday. Use toLocalDateKey() from public/utils/date.js on the frontend, and todayKey(db) on the server when you mean "what day is it for this household". Those two are deliberately different: todayKey follows the household time zone, toLocalDateKey must never see it or every date key in the app shifts by a day.
• Shift times are wall-clock, not instants. "22:00" means 22:00 wherever the person is. Store 'HH:MM' strings and never route them through new Date(...) - that is how they start travelling between time zones. A night shift is end_time < start_time, derived at read time. Do not add a crosses_midnight column: it would be a second place the same fact is written down, and the two will disagree eventually.

Resolution order

For one user and one day, in this order, first hit wins:

1. an override for that (user_id, date_key)
2. the active pattern whose valid_from/valid_until contain the day, at its computed position
3. nothing - the day is simply not part of a schedule

If two active patterns cover the same day, the one with the later valid_from wins, and the API returns a warning alongside the result rather than picking silently. Overlapping patterns are a user error worth naming, not worth rejecting at write time - people build the next rotation before the old one ends.

Surface

• GET /api/v1/schedule/entries?from=&to=&user_id= computes the window. Nothing is materialised into events. The calendar reads this feed the way it already reads holidays and birthdays, and the overlay is toggleable there.
• CRUD under /api/v1/schedule/shift-types, /patterns, /patterns/:id/days, /overrides.
• Everyone in the household can read everyone's schedule - the point of the module is that the family can see it. Writing is limited to your own patterns and overrides, with admins able to edit anyone's, matching how the task lock works.

To your second question - what the household sees - my instinct was that a quieter marker is enough, but you live with it and I would rather have the model carry both: the entry returns the shift type with its times, and whether the calendar draws a full block or a strip is a display setting, not a data one. The short_code column exists so the compact form has something to show.

Module registration

schedule goes into the module list in server/permissions.js with labelKey: 'nav.schedule' and a Lucide icon, and the migration adds it to the disabled_modules array in sync_config so existing households get it switched off, the way Inventory shipped. A household that wants it turns it on; nobody finds a new nav entry after an update they did not ask for.

Tests

test/test-schedule.js with a test:schedule script, network-free against in-memory SQLite like the rest of the suite. The cases I would want to see red before they go green:

• a date before the anchor resolves to the right position (the negative modulo)
• a cycle spanning a DST change keeps its position (build the case for a zone with DST, not for UTC - the CI runs in UTC and cannot see this class of bug otherwise)
• a night shift crossing midnight belongs to its start day
• deleting a shift type that a pattern day references fails
• an override with a NULL type produces a free day, and removing the override restores the pattern's day
• resolution order: override beats pattern beats nothing

Where to stop

First version: fixed weekly patterns, rotating cycles, per-day overrides, calendar overlay. Out: shift swapping between members as a workflow, time-off requests and approvals, anything with staffing levels. If v1 lands well, "who else is working tomorrow" is the obvious second step, and it is much easier to add on top of this than to carve out of a bigger first attempt.

Fire away with questions before you write code rather than after - and if any of the above reads wrong against how your rota actually works, say so now. I would rather change the model on this page than in a migration.

[ulsklyc]

Released in v2.48.0. Schedule is in, contributed by @mclgoerg - the cycle model above is what shipped, unchanged in its architecture.

What landed, against the decisions in this thread:

• One model, not two. A fixed weekly timetable is a 14-day cycle anchored to a date, so Weekly Timetable #749 is covered by the same arithmetic rather than by a second feature.
• A pattern, not calendar recurrence. Entries are computed when read, never copied into the calendar. Changing a pattern cannot leave stale appointments behind, and a two-year rotation costs one row instead of roughly seven hundred.
• The calendar shows it as a read-only layer, explicitly toggleable - a compact strip by default, full blocks on request - and never as ordinary editable events.
• Reading is household-wide, writing is personal. Every member sees the overlay, because the everyday question is "is Anna free on Tuesday evening"; a member writes only their own schedule, administrators write for anyone.
• The module ships switched off, the way Inventory does.

Closing this as resolved. #749 stays open on its own: the machinery is now there, and what is left for it is the timetable's own vocabulary rather than the cycle arithmetic.