NightShift Nurse – Technical System Documentation

1. Executive Summary

NightShift Nurse is a highly specialized, intelligent shift planner developed exclusively for nursing professionals and medical staff. The application addresses one of the biggest problems in the nursing industry: burnout and physical exhaustion due to irregular shift work. The core value of the app lies in the combination of scientifically based fatigue tracking (fatigue management), predictive shift planning using local pattern recognition, and a karma-based emergency coverage system for teams.

2. Architecture & Tech Stack

The application is based on a modern, scalable Flutter architecture with a strong focus on offline-first capabilities and reactive state management.

• Framework: Flutter (Version 3.x)
• State Management: Riverpod (flutter_riverpod) – Used for dependency injection and reactive state management throughout the app to ensure a clean separation of UI and business logic.
• Local Databases (Offline-First):

* Hive (hive_flutter): Serves as the primary local data store for shifts, templates, and settings. Ensures extremely fast read/write access and full functionality without an internet connection. Type adapters for domain-specific models (such as Shift and ShiftTemplate) are implemented. * SharedPreferences: Used supplementarily for rudimentary state values (e.g., onboarding status).

• Cloud & Synchronization (Premium Feature):

* Firebase (Core, Auth, Firestore, Storage): Used for real-time synchronization of team data, chats, emergency coverage requests, and optional cloud backups.

• Key Packages:

* health: Enables native integration of Apple HealthKit and Google Fit to read sleep data, step counters, and heart rate. * fl_chart: Complex data visualizations for the fatigue dashboard and earnings statistics. * table_calendar: The interactive foundation for visual shift planning. * encrypt: Ensures the local encryption of sensitive health and shift data (Secure Storage).

• Architectural Pattern: The codebase is strictly feature-based structured (lib/features/, lib/core/, lib/services/, lib/models/), which facilitates maintainability and extensibility for growing teams.

3. Detailed Feature Guide

3.1 Intelligent Shift Planning & Local AI Auto-Fill

In addition to manual entry and the use of templates (ShiftTemplates), the app features an intelligent Auto-Fill Service.

• Pattern Recognition: The algorithm analyzes historical shift data for rotation patterns, weekly constants, and cyclic repetitions.
• Prediction: Based on calculated confidence values, the system automatically suggests future shifts, which drastically reduces the administrative effort for nurses.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

3.2 Scientific Fatigue Tracking (Fatigue Management)

This is the unique selling proposition of the app. The FatigueCalculatorV2 uses an algorithm based on the scientific NASA Task Load Index (TLX). It calculates a fatigue score (0-100) based on four weighted factors: 1. Shift Pattern Analysis (40%): Detects circadian disruptions, such as rapid turnovers (< 24h) or particularly stressful night-to-day transitions. 2. Sleep Deficit (30%): Directly accesses the user’s actual hours of sleep (via HealthKit/Google Fit) using the HealthDataService. 3. Consecutive Night Shifts (20%): Considers the exponentially increasing fatigue starting from the third night shift. 4. Total Working Hours (10%): Identifies moderate to excessive overtime over the last 7 days.

The app then generates a risk level (Normal to Critical) and provides concrete, preventive action recommendations.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

3.3 Emergency Coverage System

The EmergencyCoverageService digitizes and optimizes the search for shift replacements in case of illness:

• Priority Scoring: Each request receives an urgency score calculated from the short notice (time until shift start), the requester’s fatigue score, and general urgency.
• Karma System: To gamify mutual helpfulness, users who take over emergency shifts receive +15 Karma points. The requester is deducted 5 points.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

3.4 Team Management & Communication

• Organization of nursing teams with admin rights.
• An integrated team chat (Firestore-based) allows for quick coordination and the sharing of handover notes (SBAR method).

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

4. Privacy & Security

Due to the processing of highly sensitive occupational and health data, the app is subject to strict privacy policies, fully designed for App Store and GDPR compliance:

• Offline-First & Decentralization: By default, all shift and health data (sleep, heart rate) remains encrypted on the local device (Hive).

No Unauthorized Data Collection: Health data is processed exclusively on the device for fatigue calculation and is not* sent to external servers.

• GDPR Service: A dedicated GDPRService allows the user to do the following at the push of a button:

* Article 20 (Data Portability): A complete export of all user data (Hive and Firestore) as a formatted JSON file. * Article 17 (Right to Erasure): The complete, irrevocable deletion of all local databases, cloud documents, and the auth account.

5. Monetization (NightShift PRO)

The application uses a freemium model with in-app purchases (in_app_purchase).

• Pricing Structure: A subscription model offers options for €1.99 per month, €19.99 per year (Best Value), or a lifetime unlock for €49.99. A 7-day trial period is included.
• PRO Features (Paywall):

1. Exact Earnings (Earnings Calculation): Detailed tracking of salaries, allowances, and overtime. 2. Team Admin: The ability to create new teams and invite colleagues. 3. Cloud Backup: Secure synchronization of shift schedules with Firebase to prevent data loss when changing devices. 4. Ad-Free Experience: Removal of all ad banners for a distraction-free experience.

6. User Manual (User Instructions)

Step 1: Initial Setup and Permissions

Launch the app and complete the onboarding. Grant permissions for Apple HealthKit or Google Fit when requested. This is the only way the algorithm can read your sleep data and accurately warn you about fatigue.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

Step 2: Populate the Shift Schedule

Navigate to the calendar tab. Add your upcoming shifts either manually via the “plus” icon or define recurring shift templates in the settings. Once you have entered 7 shifts, the “Auto-Fill” assistant begins to learn your shift pattern and automatically suggest future shifts.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

Step 3: Check the Fatigue Dashboard

Before accepting voluntary extra shifts, you should check the “Fatigue” dashboard. A red status (Critical) with a high score warns you that your sleep deficit or circadian rhythm is disrupted. In this case, follow the displayed recommendations (e.g., “Priority: At least 7-8 hours of sleep”).

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]

Step 4: Emergency Coverage & Teamwork

If you are unable to work on short notice, navigate to the “Team” tab and select “Emergency Coverage”. Create a request. The algorithm prioritizes your request and sends push notifications to all team members. Pick up shifts from colleagues yourself to increase your karma level within the team.

[SCREENSHOT-PLATZHALTER: Insert relevant screenshot for the above feature/step here.]