# ShiftOps Documentation

Complete documentation for the ShiftOps tool, covering architecture, API, development workflows, and troubleshooting.

## Related Cursor Rules

When working with ShiftOps, the following Cursor rules apply:

- **[shiftops-backend.mdc](../../../.cursor/rules/shiftops-backend.mdc)** - Backend API and analyzer patterns
- **[shiftops-frontend-core.mdc](../../../.cursor/rules/shiftops-frontend-core.mdc)** - Frontend workflows and data flow
- **[shiftops-frontend-qa.mdc](../../../.cursor/rules/shiftops-frontend-qa.mdc)** - QA checklist and advanced patterns
- **[api-endpoints-core.mdc](../../../.cursor/rules/api-endpoints-core.mdc)** - API endpoint patterns
- **[shared-patterns.mdc](../../../.cursor/rules/shared-patterns.mdc)** - Universal validation checklist
- **[global.mdc](../../../.cursor/rules/global.mdc)** - Planning requirements (always applies)

See [docs/ai/RULE_TO_DOC_MAPPING.md](../../ai/RULE_TO_DOC_MAPPING.md) for complete rule-to-documentation mapping.

## Overview

ShiftOps is Ordio's intelligent shift planning analysis tool that helps businesses optimize their workforce scheduling. This documentation covers all aspects of ShiftOps development and maintenance.

### Google Maps API key (ShiftOps only)

**Full runbook (rotation, monitoring, GCP restrictions):** [`SHIFTOPS_GOOGLE_MAPS_API_KEYS.md`](SHIFTOPS_GOOGLE_MAPS_API_KEYS.md)

ShiftOps uses **`ordio_get_shiftops_google_maps_api_key()`** — it does **not** override site-wide `GOOGLE_MAPS_API_KEY` (product / other pages stay on existing env keys).

For the referrer-restricted GCP key `website-maps-shiftops`, configure **one** of:

1. **Recommended:** `GOOGLE_MAPS_SHIFTOPS_API_KEY` on the server (Docker, systemd, etc.).
2. **Alternative:** copy `v2/config/google-maps-shiftops-api-key.php.example` to `v2/config/google-maps-shiftops-api-key.php`, set `api_key`; file is **gitignored**.

If neither is set, ShiftOps falls back to `ordio_get_google_maps_api_key()` (legacy dev behavior).

Server-side Places (`nearbysearch` from PHP) may need a separate **IP-restricted** key in GCP (`maps-prod-server`); that is independent of this browser key.

## Documentation Files

### Scoring System Documentation

- **[Scoring System Documentation](SHIFTOPS_SCORING_SYSTEM.md)** - Complete scoring system documentation with all factors, calculations, and examples
- **[Scoring Quick Reference](SHIFTOPS_SCORING_ai//QUICK_REFERENCE.md)** - Quick lookup for scoring constants, ranges, and common patterns

### Team Estimation Documentation

- **[Team Estimation Summary](TEAM_ESTIMATION_SUMMARY.md)** - High-level overview and quick links
- **[Team Estimation Quick Reference](TEAM_ESTIMATION_ai//QUICK_REFERENCE.md)** - Quick lookup for validation bounds, code locations, debugging
- **[Team Estimation Changelog](TEAM_ESTIMATION_CHANGELOG.md)** - Complete changelog of all changes
- **[Team Estimation Current Logic](TEAM_ESTIMATION_CURRENT_LOGIC.md)** - Detailed implementation documentation
- **[Team Estimation Enhanced Model](TEAM_ESTIMATION_ENHANCED_MODEL.md)** - Enhanced model design
- **[Team Estimation Data Flow](TEAM_ESTIMATION_DATA_FLOW.md)** - Data flow paths and storage locations
- **[Team Estimation Improvements Applied](TEAM_ESTIMATION_IMPROVEMENTS_APPLIED.md)** - Summary of improvements
- **[Team Estimation Final Status](TEAM_ESTIMATION_FINAL_STATUS.md)** - Final implementation status

### [API Documentation](SHIFTOPS_API_DOCUMENTATION.md)

Complete API reference for ShiftOps endpoints.

**Topics covered:**

- API endpoints and parameters (including NPS survey endpoint)
- Request/response formats
- Authentication and security
- Rate limiting
- Error handling
- Example requests

### [Architecture](SHIFTOPS_ARCHITECTURE.md)

System architecture and design documentation.

**Topics covered:**

- System overview
- Component architecture
- Data flow
- Database schema
- Integration points
- Technology stack

### [Development Checklist](SHIFTOPS_DEVELOPMENT_CHECKLIST.md)

Development workflow and quality assurance checklist.

**Topics covered:**

- Development workflow
- Code review checklist
- Testing requirements
- Deployment process
- QA checklist

### [Quick Reference](SHIFTOPS_ai//QUICK_REFERENCE.md)

Quick lookup guide for common tasks and patterns.

**Topics covered:**

- Common code patterns
- Frequently used functions
- Configuration options
- Quick troubleshooting
- Useful commands

### [Troubleshooting](SHIFTOPS_TROUBLESHOOTING.md)

Common issues and solutions.

**Topics covered:**

- Common errors and fixes
- Debugging techniques
- Performance issues
- Integration problems
- Known limitations
- Latest fixes (mbstring fallback, customer matching, path resolution)

### SEO Documentation

- **[SEO Monitoring Guide](SHIFTOPS_SEO_MONITORING_GUIDE.md)** - Monitoring and tracking guide for SEO performance
- **[SEO Documentation Index](seo/README.md)** - Complete SEO, AEO, and GEO documentation

**SEO Topics covered:**

- SEO/AEO/GEO enhancements
- Schema markup validation
- Monitoring and tracking
- Deployment checklists
- Quick reference guides

### [Data Structures](SHIFTOPS_DATA_STRUCTURES.md)

Complete reference for all data structures used in ShiftOps.

**Topics covered:**

- API request/response structures
- Internal data structures
- localStorage formats (including NPS survey keys)
- Component data structures
- TypeScript-like definitions with examples

### [Components](SHIFTOPS_COMPONENTS.md)

Complete reference for all PHP classes and methods.

**Topics covered:**

- ShiftOpsAnalyzer class (all methods)
- ShiftOpsCustomerMatcher class
- ShiftOpsCostCalculator class
- ShiftOpsCompetitiveAnalyzer class
- ShiftOpsRecommendationsEngine class
- ShiftOpsUserExplanations class
- NPS Survey feature (frontend and API)
- Component dependencies and error handling

### [Developer Guide](SHIFTOPS_DEVELOPER_GUIDE.md)

Complete guide for developers working on ShiftOps.

**Topics covered:**

- Setup and installation
- Development workflow
- Common tasks (adding scoring factors, recommendations, etc.)
- Debugging techniques
- Performance optimization
- Testing procedures
- Deployment checklist
- Best practices

## Related Cursor Rules

- [shiftops-backend.mdc](../../.cursor/rules/shiftops-backend.mdc) - Backend API and analyzer rules
- [shiftops-frontend.mdc](../../.cursor/rules/shiftops-frontend.mdc) - Frontend UI and workflow rules

## Quick Links

- **API Reference** → [API Documentation](SHIFTOPS_API_DOCUMENTATION.md)
- **System Design** → [Architecture](SHIFTOPS_ARCHITECTURE.md)
- **Data Structures** → [Data Structures](SHIFTOPS_DATA_STRUCTURES.md)
- **Components** → [Components](SHIFTOPS_COMPONENTS.md)
- **Developer Guide** → [Developer Guide](SHIFTOPS_DEVELOPER_GUIDE.md) (NEW)
- **Development Workflow** → [Development Checklist](SHIFTOPS_DEVELOPMENT_CHECKLIST.md)
- **Common Tasks** → [Quick Reference](SHIFTOPS_ai//QUICK_REFERENCE.md)
- **Scoring System** → [Scoring Documentation](SHIFTOPS_SCORING_SYSTEM.md)
- **Issues & Fixes** → [Troubleshooting](SHIFTOPS_TROUBLESHOOTING.md)
- **SEO & Performance** → [SEO Documentation](seo/README.md)

## Development Workflow

1. **Start Here:** Read [Developer Guide](SHIFTOPS_DEVELOPER_GUIDE.md) for setup and workflow
2. **Understand System:** Review [Architecture](SHIFTOPS_ARCHITECTURE.md) to understand system design
3. **API Reference:** Check [API Documentation](SHIFTOPS_API_DOCUMENTATION.md) for endpoint details
4. **Data Formats:** Review [Data Structures](SHIFTOPS_DATA_STRUCTURES.md) for request/response formats
5. **Components:** Check [Components](SHIFTOPS_COMPONENTS.md) for class and method documentation
6. **Development:** Follow [Development Checklist](SHIFTOPS_DEVELOPMENT_CHECKLIST.md) for workflow
7. **Quick Lookup:** Use [Quick Reference](SHIFTOPS_ai//QUICK_REFERENCE.md) for common patterns
8. **Troubleshooting:** Consult [Troubleshooting](SHIFTOPS_TROUBLESHOOTING.md) if issues arise

## Contributing

When updating ShiftOps documentation:

1. Keep API documentation in sync with code changes
2. Update architecture diagrams when system changes
3. Add new troubleshooting entries for recurring issues
4. Update quick reference with new patterns
5. Keep development checklist current with workflow changes

## Back to Documentation

← [Back to Documentation Index](../README.md)