PTO Manager

A modern contractor time-off tracking application that integrates with Outlook Calendar to automatically detect PTO events and manage balance deduction.

Features

• 🔐 Microsoft OAuth2 Integration - Secure authentication with Microsoft accounts
• 📅 Automatic Calendar Sync - Detects PTO events from Outlook Calendar automatically
• ⚖️ Smart Balance Tracking - Real-time PTO balance calculations with business day precision
• 📊 Interactive Dashboard - Clean, responsive interface showing balance and PTO history
• 🎯 Keyword Detection - Customizable keywords for automatic PTO event recognition
• 📱 Mobile Responsive - Works seamlessly on desktop, tablet, and mobile devices
• ⚡ Performance Optimized - <2s page loads, <5s calendar sync
• 🧪 Well Tested - Comprehensive test coverage with unit, integration, and E2E tests

Quick Start

Prerequisites

• Node.js 18.x or later
• PostgreSQL 14.x or later
• Microsoft Azure AD App with Calendar.Read permissions

Installation

1. Clone the repository

   git clone https://github.com/your-org/pto-manager.git
   cd pto-manager

2. Set up environment variables

   # Copy environment template
   cp .env.example .env
   
   # Edit .env with your configuration
   nano .env

3. Install dependencies

   # Backend dependencies
   cd backend
   npm install
   
   # Frontend dependencies
   cd ../frontend
   npm install

4. Set up the database

   # Start PostgreSQL (using Docker)
   docker run --name pto-postgres \
     -e POSTGRES_USER=ptomanager \
     -e POSTGRES_PASSWORD=dev_password \
     -e POSTGRES_DB=pto_manager_dev \
     -p 5432:5432 -d postgres:14
   
   # Run migrations
   cd backend
   npm run db:migrate

5. Start the development servers

   # Terminal 1: Backend server
   cd backend
   npm run dev
   
   # Terminal 2: Frontend server
   cd frontend
   npm run dev

6. Open your browser

   • Frontend: http://localhost:3001
   • Backend API: http://localhost:3000

Project Structure

├── backend/                 # Node.js/Express API server
│   ├── src/
│   │   ├── models/         # Data models (Contractor, PTOEntry, etc.)
│   │   ├── services/       # Business logic services
│   │   ├── api/           # REST API endpoints
│   │   ├── middleware/    # Authentication, error handling
│   │   └── utils/         # Utilities (date, encryption, etc.)
│   ├── tests/             # Backend tests
│   └── migrations/        # Database schema migrations
├── frontend/               # React/TypeScript client
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── services/      # API client, authentication
│   │   ├── hooks/         # Custom React hooks
│   │   └── utils/         # Client-side utilities
│   └── tests/             # Frontend tests
└── specs/                 # Project specifications and docs

Configuration

Environment Variables

Create a .env file in the project root:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/pto_manager_dev"

# Microsoft Graph API
MICROSOFT_CLIENT_ID="your_azure_app_client_id"
MICROSOFT_CLIENT_SECRET="your_azure_app_client_secret"
MICROSOFT_TENANT_ID="common"
MICROSOFT_REDIRECT_URI="http://localhost:3000/auth/callback"

# Application Configuration
JWT_SECRET="your_jwt_secret_key_here"
NODE_ENV="development"
PORT=3000
FRONTEND_URL="http://localhost:3001"

# Security
ENCRYPTION_KEY="your_32_character_encryption_key"

Microsoft Azure Setup

1. Register an application in Azure AD
2. Configure redirect URI: http://localhost:3000/auth/callback
3. Grant API permissions:
   • Calendars.Read (Delegated)
   • User.Read (Delegated)
4. Generate a client secret
5. Note the Application (client) ID

Usage

First-Time Setup

1. Sign in with Microsoft - Click the login button and authenticate with your Microsoft account
2. Set PTO Allocation - Configure your annual PTO days in Settings
3. Customize Keywords - Add custom keywords for PTO detection (optional)
4. Sync Calendar - Click "Sync Calendar" to import existing PTO events

Daily Usage

• Dashboard shows your current balance and recent PTO entries
• Sync Calendar button updates from Outlook Calendar
• PTO History page shows all your time-off entries with filtering
• Settings page allows you to update allocation and preferences

Manual PTO Entries

You can manually add PTO entries that won't sync from calendar:

1. Go to Dashboard or PTO History
2. Click "Add Manual Entry"
3. Fill in dates and description
4. Entry will be included in balance calculations

API Documentation

The complete API documentation is available in OpenAPI format:

• Local Development: http://localhost:3000/api-docs
• Specification File: specs/001-pto-manager-contractor/contracts/api-spec.yaml

Key Endpoints

• POST /api/v1/auth/login - Initiate OAuth2 login
• POST /api/v1/auth/callback - Handle OAuth2 callback
• GET /api/v1/contractor/profile - Get contractor profile
• POST /api/v1/calendar/sync - Sync calendar events
• GET /api/v1/pto/entries - Get PTO entries
• GET /api/v1/pto/balance - Get current balance
• POST /api/v1/pto/entries - Create manual PTO entry

Development

Available Scripts

Backend:

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run start        # Start production server
npm test             # Run all tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run lint         # Run ESLint
npm run db:migrate   # Run database migrations
npm run db:seed      # Seed database with test data

Frontend:

npm run dev          # Start Vite development server
npm run build        # Build production bundle
npm run preview      # Preview production build
npm test             # Run Jest tests
npm run test:watch   # Run tests in watch mode
npm run test:e2e     # Run Playwright E2E tests
npm run lint         # Run ESLint
npm run format       # Format code with Prettier

Testing

The project includes comprehensive testing at multiple levels:

• Unit Tests - Business logic, utilities, components
• Integration Tests - API endpoints, database operations
• Contract Tests - Microsoft Graph API compatibility
• E2E Tests - Complete user workflows
• Performance Tests - Load times, memory usage

# Run all tests
npm test

# Run specific test types
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:performance

# Generate coverage report
npm run test:coverage

Code Quality

• TypeScript - Type safety and better developer experience
• ESLint - Code linting with React and TypeScript rules
• Prettier - Code formatting
• Husky - Git hooks for pre-commit checks
• Jest - Unit and integration testing
• Playwright - End-to-end testing

Architecture

Tech Stack

Backend:

• Runtime: Node.js 18+
• Framework: Express.js
• Language: TypeScript
• Database: PostgreSQL with connection pooling
• Authentication: OAuth2 + JWT
• API Integration: Microsoft Graph SDK
• Testing: Jest, Supertest

Frontend:

• Framework: React 18
• Language: TypeScript
• Build Tool: Vite
• State Management: React Query (TanStack Query)
• Styling: Tailwind CSS
• UI Components: Headless UI
• Testing: Jest, React Testing Library, Playwright

Key Design Decisions

• OAuth2 PKCE Flow for secure authentication
• Server-side token storage with encryption at rest
• Business day calculations exclude weekends and holidays
• Real-time balance updates after any PTO changes
• Responsive design with mobile-first approach
• Performance optimized with caching and lazy loading

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow existing code style (ESLint + Prettier)
• Update documentation for API changes
• Use conventional commit messages
• Ensure all tests pass before submitting PR

Performance

Benchmarks

• Dashboard Load Time: <2 seconds
• Calendar Sync: <5 seconds for 200+ events
• API Response Time: <500ms for most endpoints
• Memory Usage: <50MB increase during normal usage

Optimization Features

• React Query for intelligent caching and background updates
• Database indexing for fast PTO entry queries
• Batch processing for large calendar syncs
• Lazy loading for non-critical components
• Compressed responses with gzip

Security

• OAuth2 + PKCE for secure authentication
• JWT tokens with reasonable expiration times
• Encrypted token storage using AES-256
• Input validation on all API endpoints
• CORS protection for cross-origin requests
• Rate limiting to prevent abuse
• Security headers (helmet.js)

Deployment

Production Deployment

1. Environment Setup

   # Set production environment variables
   export NODE_ENV=production
   export DATABASE_URL="postgresql://..."
   export MICROSOFT_CLIENT_ID="..."
   # ... other production variables

2. Build Applications

   # Build backend
   cd backend
   npm run build
   
   # Build frontend
   cd ../frontend
   npm run build

3. Database Migration

   cd backend
   npm run db:migrate

4. Start Services

   # Start backend server
   cd backend
   npm start
   
   # Serve frontend (use nginx or similar)
   # Frontend build files are in frontend/dist/

Docker Deployment

# Build images
docker build -t pto-manager-backend ./backend
docker build -t pto-manager-frontend ./frontend

# Run with docker-compose
docker-compose up -d

Troubleshooting

Common Issues

Calendar Sync Fails:

• Check Microsoft Graph API permissions
• Verify OAuth2 redirect URI configuration
• Ensure valid refresh token

Database Connection Errors:

• Verify PostgreSQL is running
• Check DATABASE_URL configuration
• Ensure database exists and migrations are applied

Authentication Issues:

• Verify Microsoft Azure AD app configuration
• Check JWT_SECRET is set correctly
• Ensure redirect URI matches exactly

Debug Mode

Enable debug logging:

export DEBUG=pto-manager:*
npm run dev

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: Project Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Microsoft Graph API for calendar integration
• React and Node.js communities
• Contributors and testers

---

Made with ❤️ for contractors who want better PTO tracking