Living Document | Version 1.0 | Status: 🟡 Planning Phase

A comprehensive online staff rota application designed for Windows/IIS deployment, implementing Cloud 4.0 principles for modern, scalable workforce management. The system provides role-based access control, intelligent shift scheduling, automated notifications, and comprehensive reporting capabilities.

To create a maintainable, modular, and user-friendly staff scheduling solution that grows with organizational needs while maintaining simplicity and reliability.

• User adoption rate > 90% within 3 months
• Shift swap processing time < 24 hours
• Email notification delivery rate > 98%
• System uptime > 99.5%

• Modularity: Component-based architecture with clear separation of concerns
• Scalability: Horizontal scaling support through stateless design
• Observability: Comprehensive logging, monitoring, and health checks
• Resilience: Graceful degradation and error recovery mechanisms

┌─────────────────────────────────────────────────┐
│                   Frontend                      │
├─────────────────────────────────────────────────┤
│ Option A: ASP.NET Core MVC with Razor Pages    │
│ Option B: React SPA with .NET Core Web API     │
│ Option C: Angular SPA with .NET Core Web API   │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│                   Backend                       │
├─────────────────────────────────────────────────┤
│ .NET 8.0 (LTS) - Primary Choice                │
│ - ASP.NET Core Web API                          │
│ - Entity Framework Core                         │
│ - Identity Framework for Authentication         │
│ - Background Services for Email Tasks           │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│                  Data Layer                     │
├─────────────────────────────────────────────────┤
│ Option A: SQL Server Express (Recommended)     │
│ Option B: MySQL 8.0+                           │
│ Option C: SQLite (for smaller deployments)     │
│ Option D: JSON Flat Files (development only)   │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│                Infrastructure                   │
├─────────────────────────────────────────────────┤
│ - Windows Server 2019/2022 + IIS 10+           │
│ - SMTP Service (Exchange/SendGrid/Gmail)        │
│ - SSL/TLS Certificates                          │
│ - Application Insights (Optional)               │
└─────────────────────────────────────────────────┘

• Primary Users: Front-line staff, part-time employees
• Responsibilities: Work assigned shifts, manage personal availability
• Key Actions: View schedule, request time off, initiate shift swaps

• Primary Users: Supervisors, department heads, shift managers
• Responsibilities: Schedule team members, approve requests, monitor coverage
• Key Actions: Create rotas, approve swaps, manage team schedules

• Primary Users: HR personnel, system administrators, senior management
• Responsibilities: System configuration, user management, compliance reporting
• Key Actions: User administration, system settings, comprehensive reporting

graph TD
    A[User Visits Site] --> B{Authenticated?}
    B -->|No| C[Login Page]
    B -->|Yes| D[Dashboard]
    C --> E[Enter Credentials]
    E --> F{Valid Credentials?}
    F -->|No| G[Show Error + Login Page]
    F -->|Yes| H[Create Session]
    H --> I[Set Auth Cookie]
    I --> D
    D --> J[Role-Based Content]
    G --> E

• Password Requirements:
  • Minimum 8 characters
  • At least 1 uppercase, 1 lowercase, 1 number
  • Optional special character requirement
• Session Management:
  • HTTP-only secure cookies
  • 8-hour session timeout
  • Sliding expiration
• Brute Force Protection:
  • Account lockout after 5 failed attempts
  • 15-minute lockout period
  • Progressive delays between attempts

├── Models/
│   ├── User.cs (User entity with hashed passwords)
│   ├── Role.cs (Role definitions)
│   └── UserRole.cs (User-Role mapping)
├── Services/
│   ├── AuthenticationService.cs
│   ├── PasswordHashingService.cs
│   └── SessionService.cs
├── Controllers/
│   ├── AuthController.cs
│   └── AccountController.cs
└── Views/
    ├── Login.cshtml
    ├── Register.cshtml (Admin only)
    └── Profile.cshtml

public class Shift
{
    public int Id { get; set; }
    public DateTime StartDateTime { get; set; }
    public DateTime EndDateTime { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public int AssignedUserId { get; set; }
    public int CreatedByUserId { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? ModifiedAt { get; set; }
    public ShiftStatus Status { get; set; }
    public string Location { get; set; }
    public decimal? PayRate { get; set; }
}

public enum ShiftStatus
{
    Draft,
    Published,
    Assigned,
    SwapRequested,
    Completed,
    Cancelled
}

graph TD
    A[Team Lead Opens Shift Creator] --> B[Select Date Range]
    B --> C[Define Shift Details]
    C --> D[Choose Assignment Method]
    D --> E{Auto-Assign?}
    E -->|Yes| F[System Assigns Based on Availability]
    E -->|No| G[Manual Staff Selection]
    F --> H[Send Notification to Assigned Staff]
    G --> H
    H --> I[Shift Published to Rota]
    I --> J[Update Team Calendar]

• Availability Checking: Cross-reference with existing assignments
• Fair Distribution: Rotation algorithm to ensure equitable shift distribution
• Skill Matching: Match shift requirements with staff qualifications
• Preference Weighting: Consider staff preferences for days/times

graph TD
    A[Team Member Requests Swap] --> B[Select Shift to Swap]
    B --> C[Choose Target Staff Member]
    C --> D[System Validates Availability]
    D --> E{Validation Passed?}
    E -->|No| F[Show Error + Suggestions]
    E -->|Yes| G[Create Swap Request]
    G --> H[Notify Target Staff Member]
    H --> I{Target Accepts?}
    I -->|No| J[Notify Requester of Rejection]
    I -->|Yes| K[Notify Team Lead for Approval]
    K --> L{Team Lead Approves?}
    L -->|No| M[Notify Both Parties of Rejection]
    L -->|Yes| N[Execute Swap]
    N --> O[Update Rota]
    O --> P[Send Confirmation Emails]
    F --> C
    J --> A
    M --> A

• Time Restrictions: Swaps must be requested 48+ hours before shift start
• Skill Requirements: Replacement must meet minimum qualifications
• Approval Chain: Team Lead approval required for all swaps
• Swap Limits: Maximum 3 pending swap requests per user
• Blackout Periods: No swaps during critical business periods

1. Shift Assignments

   • New shift assigned
   • Shift updated/cancelled
   • Shift reminder (24h before)

2. Swap Requests

   • Swap request received
   • Swap request accepted/declined
   • Swap approved by Team Lead

3. Weekly Reminders

   • Friday reminder for upcoming week
   • Monthly schedule summary

4. Administrative

   • Account created/activated
   • Password reset
   • System maintenance notifications

├── Services/
│   ├── EmailService.cs (SMTP wrapper)
│   ├── TemplateEngine.cs (HTML template processing)
│   └── NotificationScheduler.cs (Background service)
├── Templates/
│   ├── ShiftAssignment.html
│   ├── SwapRequest.html
│   ├── WeeklyReminder.html
│   └── _Layout.html (Common layout)
├── Models/
│   ├── EmailMessage.cs
│   ├── EmailTemplate.cs
│   └── EmailQueue.cs
└── Background/
    ├── WeeklyReminderJob.cs
    └── EmailProcessingService.cs

• Schedule: Every Friday at 5:00 PM
• Recipients: All active team members with shifts in upcoming week
• Content:
  • Summary of upcoming shifts
  • Important notices/changes
  • Contact information for questions
• Retry Logic: 3 attempts with exponential backoff

{
  "EmailSettings": {
    "SmtpHost": "smtp.gmail.com",
    "SmtpPort": 587,
    "EnableSsl": true,
    "Username": "[SMTP_USERNAME]",
    "Password": "[SMTP_PASSWORD]",
    "FromAddress": "[email protected]",
    "FromName": "Staff Rota System"
  }
}

• Daily Shift Coverage: Real-time view of today's assignments
• Weekly Rota Summary: Complete week view with gaps/conflicts
• Monthly Attendance: Individual and team attendance tracking
• Shift Swap Analytics: Frequency, patterns, approval rates

• Staff Utilization: Hours worked vs. availability
• Cost Analysis: Labor costs by department/period
• Overtime Tracking: Hours beyond standard shifts
• Compliance Reports: Regulatory requirement adherence

• User Activity: Login patterns, feature usage
• System Health: Performance metrics, error rates
• Audit Trail: All system changes and access logs

public interface IExportService
{
    Task<byte[]> ExportToCsv(ReportData data);
    Task<byte[]> ExportToPdf(ReportData data);
    Task<byte[]> ExportToExcel(ReportData data);
    Task<string> GenerateEmailReport(ReportData data);
}

• Ad-hoc Generation: On-demand report creation
• Scheduled Reports: Weekly/monthly automated delivery
• Real-time Dashboards: Live data visualization
• Historical Trending: Month-over-month comparisons

Duration: 1-2 days | Status: ✅ Complete | Priority: Critical

• Project repository structure
• Living document (this file) creation
• Initial technology stack decisions
• Development environment setup
• Project planning and phase definition

StaffRota/
├── docs/
│   ├── Project.md (this file)
│   ├── API-Documentation.md
│   └── Deployment-Guide.md
├── src/
│   ├── StaffRota.Web/
│   ├── StaffRota.Core/
│   ├── StaffRota.Data/
│   └── StaffRota.Tests/
├── database/
│   ├── migrations/
│   └── seed-data/
├── deployment/
│   ├── iis-config/
│   └── scripts/
└── README.md

Developer Notes: Project structure follows Clean Architecture principles for maintainability.

Duration: 3-4 days | Status: ✅ Completed | Priority: Critical

• ✅ Finalized technology stack (.NET 9.0 implemented)
• ✅ Designed and implemented comprehensive database schema
• ✅ Created data access layer with Entity Framework Core 9.0.10
• ✅ Established complete project structure with Clean Architecture

• ✅ Database schema design and initial migration created
• ✅ Complete entity models and DbContext setup
• ✅ Repository pattern implementation with specialized repositories
• ✅ Full CRUD operations for all entities via generic repository
• ✅ Connection string management and configuration
• ✅ Authentication infrastructure setup (JWT + BCrypt)
• ✅ Logging infrastructure setup (Serilog)

• Backend Framework: .NET 9.0 with ASP.NET Core
• Database: SQL Server Express (LocalDB for development)
• ORM: Entity Framework Core 9.0.10
• Authentication: JWT Bearer tokens with BCrypt password hashing
• Logging: Serilog.AspNetCore 9.0.0
• API Documentation: Swagger/OpenAPI 3.0

StaffRota.Core/
├── Entities/ (User, Shift, SwapRequest, EmailQueue, AuditLog, SystemSetting)
├── Enums/ (UserRole, ShiftStatus, SwapRequestStatus, EmailStatus)
└── Interfaces/ (Repository contracts and statistics classes)

StaffRota.Data/
├── Context/ (StaffRotaDbContext with relationship configuration)
├── Configurations/ (Fluent API configurations for all entities)
├── Repositories/ (Repository<T>, UserRepository, ShiftRepository, SwapRequestRepository, EmailQueueRepository)
└── Migrations/ (InitialCreate migration generated)

StaffRota.Web/
├── Program.cs (Complete DI container setup)
├── appsettings.json (Database connection and JWT configuration)
└── Dependencies (All necessary NuGet packages installed)

-- Successfully created with EF Core migrations
Users: Email, PasswordHash, FirstName, LastName, Role, Department, Skills, etc.
Shifts: StartDateTime, EndDateTime, Title, AssignedUserId, CreatedByUserId, Status, Location, etc.
SwapRequests: OriginalShiftId, RequestingUserId, TargetUserId, Status, RequestedAt, ApprovedAt, etc.
EmailQueue: ToAddress, Subject, Body, Status, Priority, ScheduledAt, RetryCount, etc.
AuditLogs: UserId, Action, EntityType, EntityId, Changes, Timestamp
SystemSettings: Key, Value, Description, ModifiedAt, ModifiedByUserId

-- Comprehensive indexes, constraints, and relationships implemented

• Clean Architecture: Proper separation of concerns with Core/Data/Web layers
• Repository Pattern: Generic base repository with specialized implementations
• Entity Framework: Comprehensive configurations with proper relationships
• Security Foundation: JWT authentication and BCrypt password hashing ready
• Logging Infrastructure: Structured logging with Serilog configured
• Database Design: Optimized schema with indexes and constraints
• Migration Support: EF Core migrations system established

Phase 2 Status: 🎉 COMPLETE - Ready to proceed to Phase 3 (Authentication & User Management)

Duration: 4-5 days | Status: ⬜ Not Started | Priority: Critical

• Implement secure authentication system
• Create user management functionality
• Establish role-based authorization
• Build user registration and profile management

• Local authentication with password hashing
• Role-based authorization middleware
• User registration (admin-only) functionality
• User profile management
• Password reset capability
• Session management and security

• BCrypt password hashing
• HTTPS enforcement
• CSRF protection
• Secure session management
• Input validation and sanitization

Dependencies: Phase 2 completion required.

Duration: 5-6 days | Status: ⬜ Not Started | Priority: Critical

• Build shift creation and editing functionality
• Implement shift assignment logic
• Create calendar/rota views
• Develop shift validation rules

• Shift CRUD operations
• Staff assignment to shifts
• Calendar view (weekly/monthly)
• Shift conflict detection
• Availability checking
• Bulk shift creation tools

• Shift creation form
• Interactive calendar component
• Staff assignment interface
• Conflict resolution workflow

Dependencies: Phase 3 completion required.

Duration: 3-4 days | Status: ⬜ Not Started | Priority: High

• Implement SMTP email service
• Create email templates
• Build notification scheduling
• Develop weekly reminder system

• Email service configuration
• HTML email templates
• Background email processing
• Weekly reminder scheduler
• Email queue management
• Delivery tracking and retry logic

• Shift assignment notification
• Weekly schedule reminder
• Swap request notifications
• Account creation welcome
• Password reset

Dependencies: Phase 2 completion required.

Duration: 4-5 days | Status: ⬜ Not Started | Priority: High

• Build swap request workflow
• Implement approval process
• Create swap history tracking
• Develop notification integration

• Swap request creation
• Multi-step approval workflow
• Availability validation for swaps
• Automatic rota updates
• Swap history and reporting
• Email notifications for all swap events

• Eligibility checking
• Time-based restrictions
• Approval chain implementation
• Conflict resolution

Dependencies: Phases 4 and 5 completion required.

Duration: 3-4 days | Status: ⬜ Not Started | Priority: Medium

• Create comprehensive reporting system
• Implement export functionality
• Build analytics dashboards
• Develop automated report generation

• Report generation engine
• CSV/PDF export capabilities
• Dashboard views
• Scheduled report delivery
• Custom report builder
• Data visualization components

• Weekly/monthly rotas
• Staff utilization reports
• Swap request analytics
• Attendance summaries
• Cost analysis reports

Dependencies: All core features (Phases 3-6) completion required.

Duration: 6-8 days | Status: ⬜ Not Started | Priority: High

• Create responsive user interface
• Implement interactive components
• Ensure mobile compatibility
• Integrate with backend APIs

• Responsive web design
• Interactive calendar component
• Real-time notifications
• Mobile-optimized interface
• Accessibility compliance
• Cross-browser compatibility

• Clean, professional design
• Intuitive navigation
• Fast loading times
• Touch-friendly interface
• Keyboard shortcuts

Dependencies: Backend API completion (Phases 3-7).

Duration: 4-5 days | Status: ⬜ Not Started | Priority: Critical

• Comprehensive testing suite
• Performance optimization
• Security testing
• User acceptance testing

• Unit test coverage (>80%)
• Integration tests
• Performance benchmarks
• Security vulnerability assessment
• User acceptance test scenarios
• Load testing results

• Unit tests for business logic
• API integration tests
• UI automation tests
• Security penetration testing
• Performance load testing

Dependencies: Feature completion (Phases 3-8).

Duration: 2-3 days | Status: ⬜ Not Started | Priority: Medium

• Production deployment
• Comprehensive documentation
• User training materials
• Maintenance procedures

• IIS deployment scripts
• Database deployment procedures
• User manual and training guide
• Administrator documentation
• Maintenance and backup procedures
• Monitoring and alerting setup

• Installation guide
• User manual
• API documentation
• Admin guide
• Troubleshooting guide

Dependencies: Testing completion (Phase 9).

• Overall Completion: 25% (Phase 1 ✅ Complete, Phase 2 ✅ Complete)
• Next Milestone: Complete Phase 3 (Authentication & User Management)
• Estimated Completion: November 4, 2025 (Phase 3)

• Solution Structure: Complete Clean Architecture implementation
• Database Schema: Comprehensive EF Core setup with migrations
• Repository Pattern: All specialized repositories implemented
• Authentication Foundation: JWT + BCrypt infrastructure ready
• Logging Infrastructure: Serilog configured and operational
• Build Status: All projects building successfully
• Migration Status: Initial database migration generated

• Monolith vs. Microservices: Starting with monolithic architecture for simplicity, designed for future microservices migration
• Database Strategy: Single database with clear schema boundaries to enable future service separation
• Caching Strategy: In-memory caching for frequently accessed data, Redis for production scaling
• API Design: RESTful APIs with OpenAPI documentation for future integrations

• Mobile Application: Native iOS/Android apps
• Calendar Integration: Google Calendar, Outlook synchronization
• Advanced Analytics: Predictive scheduling, pattern recognition
• Multi-tenant Support: Multiple organization support
• API Ecosystem: Third-party integration capabilities
• Real-time Updates: WebSocket-based live updates
• Advanced Notifications: SMS, push notifications
• Shift Templates: Recurring shift patterns
• Skills Matrix: Advanced skill-based assignment
• Time Tracking: Integration with time clock systems

• Database Optimization: Indexed queries, partitioning strategies
• Caching Layers: Redis implementation for session and data caching
• Load Balancing: Multi-instance deployment support
• CDN Integration: Static asset delivery optimization
• Monitoring: Application Performance Monitoring (APM) integration

• Language: C# 12.0 features where applicable
• Naming: PascalCase for public members, camelCase for private
• Documentation: XML comments for all public APIs
• Testing: Arrange-Act-Assert pattern for unit tests
• Git: Feature branch workflow with pull request reviews

• IDE: Visual Studio 2022 or VS Code
• Database Tools: SQL Server Management Studio or Azure Data Studio
• API Testing: Postman or Swagger UI
• Source Control: Git with conventional commit messages

🏗️ Architecture Notes:
- Clean Architecture pattern chosen for maintainability
- Repository pattern for data access abstraction
- Dependency injection throughout application layers

🔒 Security Considerations:
- Never store passwords in plain text
- Implement proper CSRF protection
- Validate all user inputs server-side
- Use HTTPS in production environments

⚡ Performance Considerations:
- Lazy loading for navigation properties
- Async/await for all I/O operations
- Connection pooling for database access
- Minimal API responses with selected fields only

🧪 Testing Strategy:
- Unit tests for business logic (StaffRota.Core)
- Integration tests for data access (StaffRota.Data)
- API tests for controllers (StaffRota.Web)
- End-to-end tests for critical user journeys

• After Each Phase: Update completion status and notes
• Weekly: Review progress and adjust timeline
• Monthly: Evaluate architecture decisions and future planning

• ✅ Phase Completion: Mark phases as complete with completion date
• ✅ Technical Decisions: Document all architectural choices
• ✅ Blockers & Issues: Record problems and their resolutions
• ✅ Scope Changes: Update requirements and impact assessment
• ✅ Performance Metrics: Update actual vs. planned timelines

1. Identify need for change in requirements or architecture
2. Update relevant sections in this document
3. Note change reason and impact in decision log
4. Communicate changes to all stakeholders
5. Update project timeline if necessary

Date: October 29, 2025
Updated By: GitHub Copilot
Version: 1.0
Next Review: November 1, 2025

Recent Changes:

• ✅ Initial comprehensive project scaffold created
• ✅ Complete architecture and phase planning documented
• ✅ Role definitions and permissions matrix established
• ✅ Technical stack decisions and trade-offs outlined
• ✅ Detailed implementation roadmap with dependencies

Upcoming Tasks:

• Begin Phase 2: Backend architecture implementation
• Finalize database provider selection
• Create initial project structure and dependencies
• Set up development environment and CI/CD pipeline

This document serves as the single source of truth for the Staff Rota Application project. All development decisions, progress updates, and architectural changes must be reflected here to maintain project visibility and ensure successful delivery.