Your rotation. Calculated automatically. Ready for your calendar.

---

[SYSTEM_SPEC]
Application   » ShiftFlow (Precision Work Rotation Engine)
Architecture  » 100% Stateless • Zero Database • Client-Side LocalStorage
Interop Spec  » RFC 5545 All-Day Event iCalendar Matrix (.ics)
Localization  » English & Arabic with Full Bidirectional RTL
Verification  » 13 / 13 Unit Tests Passing • Zero TypeScript Errors
Deployment    » Netlify Static Matrix (out/)

---

Problem and Overview

Workers on fixed rotation schedules (offshore oil and gas rigs, aviation, mining shifts, medical rotations, military deployments, and manufacturing) frequently need to calculate their shift schedules manually:

• When does an active work period end?
• When does a vacation or off period begin and conclude?
• What is the exact resumption date for the next shift?

Manual calendar calculations regularly introduce off-by-one errors due to inclusive date ranges, month rollovers, and leap years.

ShiftFlow automates this with mathematical precision.

START DATE  ──►  WORK DAYS  ──►  OFF DAYS  ──►  CALCULATE  ──►  EXPORT (.ICS)

No accounts. No authentication. No database. No telemetry.

---

System Architecture

graph TD
    A[User Input: Start Date, Work Days, Off Days, Horizon] --> B[ShiftFlow UI: Next.js 15 & Tailwind CSS]
    B --> C[Core Engine: lib/rotation-engine.ts]
    C --> D{Date Calculation: lib/date-utils.ts}
    D -->|Inclusive Intervals| E[Generated Periods: WORK & OFF Cycles]
    E --> F[Real-Time Status Resolver]
    E --> G[RFC 5545 ICS Builder: lib/ics-generator.ts]
    E --> H[CSV Data Stream: lib/csv-generator.ts]
    
    G -->|Exclusive DTEND Rule| I[Apple Calendar / iOS / iPadOS / macOS]
    G -->|Direct Import| J[Google Calendar / Android]
    G -->|Standard Format| K[Microsoft Outlook & Thunderbird]

Loading

---

Mathematical Date Engine

All rotation intervals in ShiftFlow are strictly inclusive:

$$\text{Duration} = (\text{End Date} - \text{Start Date}) + 1$$

Example: 23 Work / 7 Off Rotation starting 17 August 2026

Cycle Phase	Start Date	End Date	Duration	RFC 5545 DTSTART	RFC 5545 DTEND
Cycle 1 WORK	2026-08-17	2026-09-08	23 Days	20260817	20260909 (Exclusive)
Cycle 1 OFF	2026-09-09	2026-09-15	7 Days	20260909	20260916 (Exclusive)
Cycle 2 WORK	2026-09-16	2026-10-08	23 Days	20260916	20261009 (Exclusive)
Cycle 2 OFF	2026-10-09	2026-10-15	7 Days	20261009	20261016 (Exclusive)

Important

RFC 5545 Exclusive DTEND Rule: For all-day calendar events (VALUE=DATE), the RFC 5545 specification requires that DTEND is exclusive (the calendar day after the last day of the event). If a work period ends on September 8th, DTEND is set to 20260909. ShiftFlow adheres strictly to this rule for exact compatibility across Apple Calendar, Google Calendar, and Microsoft Outlook.

---

Supported Rotation Models

ShiftFlow is configurable for any rotation schedule:

• 14 / 14 — Equal Time (Offshore / Mining)
• 28 / 28 — Overseas Rig Rota (International)
• 23 / 7 — Specialized Industrial Block (Offshore Drilling)
• 7 / 7 — Standard Week-On / Week-Off
• 4 / 4 — 4-On / 4-Off Pattern
• 2 / 2 / 3 — Panama 12-Hour Shift System
• 5 / 2 — Standard Corporate Shift System
• Custom X / Y — Any custom work and off day combination (1 to 365 days)

---

Key Capabilities

• Privacy by Design: Client-side computation with local preferences stored via localStorage.
• Apple Calendar Sync: One-tap .ics import on iOS, iPadOS, and macOS with native "Add All" dialog.
• Google Calendar Ready: RFC-compliant .ics import without OAuth permission requirements.
• Bilingual & Full RTL: Native English and Arabic support powered by IBM Plex Sans Arabic.
• Status Dashboard: Live shift status, countdown metrics, active day indicator, and progress meter.
• Interactive Calendar Preview: Month view and list view with day inspection dialogs.
• Annual Analytics: Work-to-rest percentage ratio and 12-month day breakdown matrix.
• Print Engine: Dedicated printable roster sheet with @media print.
• CSV Data Export: Generate date,type,cycle,day_in_cycle,day_in_period logs.

---

Tech Stack

Frontend Framework  │ Next.js 15 (App Router, Static Export)
UI Runtime          │ React 19
Type System         │ TypeScript 5.7+ (Strict Mode)
Styling             │ Tailwind CSS 3.4
Date Engine         │ date-fns v4 (Timezone-Neutral UTC Noon Math)
Schema Validation   │ Zod 3.24
Test Runner         │ Vitest 3.0
Deployment          │ Netlify (netlify.toml)

---

Quick Start & Local Development

1. Clone and Install Dependencies

git clone https://github.com/your-username/shiftflow.git
cd shiftflow
npm install

2. Start Development Server

npm run dev

Open http://localhost:3000 in your browser.

3. Run Test Suite

npm run test

 ✓ tests/date-utils.test.ts (5 tests)
 ✓ tests/rotation-engine.test.ts (6 tests)
 ✓ tests/ics-generator.test.ts (2 tests)

 Test Files  3 passed (3)
      Tests  13 passed (13)

4. Build Production Static Bundle

npm run build

Generates optimized static HTML/JS files in the out/ directory.

---

Netlify Deployment

ShiftFlow deploys directly to Netlify as a pre-rendered static application:

1. Push the repository to GitHub.
2. Connect the repository in the Netlify dashboard.
3. Netlify automatically reads netlify.toml:
   • Build Command: npm run build
   • Publish Directory: out
   • Security Headers: Includes Content-Security-Policy, X-Frame-Options, and immutable static cache headers.

---

License

Distributed under the MIT License. Free for personal, commercial, and open-source use.

Copyright (c) 2026 ShiftFlow