diff --git a/README.md b/README.md index 3209cb5..724ab8e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ -# Refactoring & unit testing challenge +# Refactoring & Architecture Challenge ## It's great you're here! We're excited to have you at this stage of the recruitment process — and we're looking forward to seeing how you think and approach complex problems. -This task is designed not only to evaluate your ability to write clean and testable code, but more importantly -to **understand your approach to software design, architecture, and testing at a senior level.** +This task is designed to evaluate your ability to work with AI-assisted development tools (like Cursor) +while demonstrating senior-level skills in software design, architecture, testing, and business understanding. + +We encourage you to use AI tools (Cursor, GitHub Copilot, etc.) as you would in your daily work — but remember, +the quality of your architectural decisions and understanding of the business logic is what we're evaluating. ## What we're looking for? We're looking for a Senior developer who is able to work closely with business and understand the business logic and -purpose behind it. +purpose behind it. Someone who can leverage modern tools effectively while maintaining high standards of code quality +and architectural thinking. This exercise will give you space to demonstrate: @@ -18,43 +22,238 @@ This exercise will give you space to demonstrate: and valuable software solutions. - Strong understanding and application of SOLID principles. - Use of appropriate design patterns where they add clarity and value. -Awareness and thoughtful application of modern software architecture principles, clearly separating technical - concerns while maintaining deep business insight. +- Awareness and thoughtful application of modern software architecture principles, clearly separating technical + concerns while maintaining deep business insight. - A pragmatic yet rigorous approach to unit testing, emphasizing the testability of business-critical components. -- Clear, developer-friendly communication—whether through your code structure, naming conventions, or thoughtful commentary +- Clear, developer-friendly communication—whether through your code structure, naming conventions, or thoughtful commentary. - Being up to date with PHP language development and its features. +- **Ability to work with AI tools effectively** — knowing when to use them, how to guide them, and when to override their suggestions. +- **Architectural decision-making** — understanding trade-offs and making informed choices. + +## Business Context + +You're working on a **Doctor Slots Synchronization System** for Docplanner. This system: + +- Synchronizes doctor information and their available appointment slots from external vendor APIs +- Must handle multiple data sources (currently one, but designed to scale) +- Needs to be resilient to API failures and network issues +- Must maintain data consistency and handle edge cases in real-world scenarios +- Will be extended in the future with additional features (notifications, analytics, etc.) ## Task description + +### Phase 1: Understanding & Refactoring (Required) Please look at [`src/DoctorSlotsSynchronizer.php`](src/DoctorSlotsSynchronizer.php). -Your goal is to: +Your initial goals: - Clearly articulate and understand the existing business logic purely from the provided code. - Refactor the class to make it easier to test, reason about, and maintain. Think in terms of architecture, -modularity, and clarity. -- Write tests for the extracted/refactored business logic using your preferred PHP testing framework. -- If you see opportunities for improvements that go beyond the scope of the task, feel free to: - - Add them, but please remember to keep your changes minimal. - - Or simply leave comments describing your suggestions and reasoning. It's the preferred way. + modularity, and clarity. +- Write comprehensive tests for the extracted/refactored business logic using your preferred PHP testing framework. +- Document your architectural decisions (consider using ADRs - Architecture Decision Records, or at least inline comments). + +### Phase 2: New Business Requirements (Required) + +After refactoring, implement the following new features: + +#### 2.1 Multi-Source Synchronization +- The system now needs to support **multiple vendor APIs** (not just one) +- Each vendor may have different: + - Authentication methods (some use Basic Auth, others might use API keys, OAuth, etc.) + - Response formats (though they'll be normalized to the same structure) + - Rate limits and retry policies +- Design the architecture to easily add new vendors without modifying existing code + +#### 2.2 Enhanced Error Handling & Resilience +- Implement a **retry mechanism** with exponential backoff for failed API calls +- Add **circuit breaker pattern** to prevent cascading failures when a vendor API is down +- Implement proper **error categorization** (transient vs permanent errors) +- Add **dead letter queue** concept for slots that fail to sync after multiple retries +- Log errors with appropriate context for debugging + +#### 2.3 Slot Conflict Detection +- Detect and handle **slot conflicts** (overlapping slots for the same doctor) +- When conflicts are detected: + - Log them with detailed information + - Apply a conflict resolution strategy (your choice, but document it) + - Consider: should we merge, reject, or flag for manual review? + +#### 2.4 Data Validation & Business Rules +- Validate that slots make business sense: + - Start time must be before end time + - Slot duration must be within reasonable bounds (e.g., 15 minutes to 4 hours) + - Slots cannot be in the past (or handle historical data appropriately) + - Doctor names must follow certain patterns (extend the existing normalization) +- Add validation for doctor data integrity + +#### 2.5 Performance & Scalability Considerations +- The system may need to sync **thousands of doctors** with **hundreds of slots each** +- Implement **batching** or **chunking** strategies to avoid memory issues +- Consider **async processing** capabilities (you can use a simple queue interface, no need for full implementation) +- Add basic **caching** for vendor API responses where appropriate + +#### 2.6 Observability & Monitoring +- Add structured logging with different log levels +- Implement basic **metrics collection** (count of synced doctors, slots, errors, etc.) +- Add **health check endpoints** or methods to verify system status +- Consider adding **tracing** for debugging synchronization flows + +### Phase 3: Documentation & Communication (Required) + +- **Architecture Documentation**: Create a document explaining your architectural decisions +- **API Documentation**: Document any new interfaces or public APIs you create +- **Testing Strategy**: Document your testing approach and coverage +- **Deployment Considerations**: Add notes about how this would be deployed and monitored in production + +### Phase 4: Optional Enhancements (Bonus Points) + +If you have time and want to go further, consider: + +- **Event-Driven Architecture**: Implement domain events for slot creation/updates +- **CQRS Pattern**: Separate read and write models if it makes sense +- **Dockerization**: Complete dockerization of the entire application +- **CI/CD Pipeline**: Add GitHub Actions or similar for automated testing +- **Performance Testing**: Add load tests or benchmarks +- **Additional Vendor Implementation**: Implement a second mock vendor with different characteristics + +## Technical Requirements + +- Use **PHP 8.1+** features (typed properties, enums, match expressions, etc.) +- Follow **PSR standards** (PSR-4, PSR-12) +- Write **comprehensive tests** (aim for >80% coverage on business logic) +- Use **dependency injection** properly +- Consider **immutability** where it makes sense +- Use **value objects** for domain concepts where appropriate + +## Evaluation Criteria + +We'll evaluate: + +1. **Code Quality**: Clean, readable, maintainable code +2. **Architecture**: Well-structured, scalable, follows SOLID principles +3. **Business Understanding**: Correct implementation of business rules +4. **Testing**: Comprehensive, meaningful tests +5. **Documentation**: Clear explanations of decisions and trade-offs +6. **Tool Usage**: Effective use of AI tools (not just copy-paste, but thoughtful application) +7. **Problem Solving**: How you handle edge cases and unexpected scenarios -We will very much appreciate comments about why you've chosen certain solutions! +## Additional Notes & Tips -### Additional Notes & Tips -- Focus on demonstrating clarity and business-driven quality over quantity. -- You decide how much time you want to spend — quality over quantity is key. -- If something could be improved but would take too long, just leave a comment or TODO. -- If anything is unclear, don’t hesitate to reach out — asking questions is a good sign. +- **AI Tools**: Feel free to use Cursor, GitHub Copilot, ChatGPT, etc. We're evaluating your ability to work WITH these tools, not without them. However, we expect you to: + - Understand and review all generated code + - Make architectural decisions yourself + - Refactor and improve AI suggestions when needed + - Document why you made certain choices + +- **Time Management**: Focus on: + - Quality over quantity + - Clear architecture over quick hacks + - Understanding trade-offs + - Documenting your thinking + +- **Questions**: If anything is unclear, don't hesitate to reach out — asking questions is a good sign. + +- **Scope**: You don't need to implement everything perfectly. If something would take too long: + - Implement a simplified version + - Leave clear TODOs with explanations + - Document what the full implementation would look like ## How to use this repository? + +### Getting Started - To create your copy, - Use the green "Use this template" button on the top right. It should be set as private repo. - Do not use the Fork feature. -- Complete the task as described above. +- Complete the task as described above, following the phases. - When done, give access to the repo to the hiring manager and other people provided. - Send us the link to the PULL REQUEST **in your repo**, so we can review your work. -## Installation -Only the vendor API is dockerized and configured to work with `docker-compose`. However, feel free to dockerize the rest of the project if you find it helpful. -To run the container, use `docker-compose up -d`. -After a while, the vendor API serving doctors will be accessible on `http://localhost:2137`. +### Submission Guidelines +- Create a **single pull request** with all your changes +- Use **meaningful commit messages** that explain what and why +- Include a **summary** in the PR description explaining: + - Your architectural approach + - Key decisions you made + - What you prioritized and why + - Any trade-offs you considered + - How you used AI tools (if you're comfortable sharing) + +## Installation & Setup + +### Prerequisites +- PHP 8.1 or higher +- Composer +- Docker and Docker Compose (for the vendor API) + +### Setup Steps + +1. **Install dependencies:** + ```bash + composer install + ``` + +2. **Start the vendor API:** + ```bash + docker-compose up -d + ``` + After a while, the vendor API serving doctors will be accessible on `http://localhost:2137`. + +3. **Test the API is working:** + ```bash + curl -u docplanner:docplanner http://localhost:2137/api/doctors + ``` + +4. **Run tests** (after you set up your testing framework): + ```bash + # Example with PHPUnit + vendor/bin/phpunit + ``` + +### Vendor API Endpoints + +The vendor API provides the following endpoints: + +- `GET /api/doctors` - Returns list of doctors (requires Basic Auth: docplanner/docplanner) +- `GET /api/doctors/{id}/slots` - Returns slots for a specific doctor + +**Note:** The API may occasionally return errors or be slow to simulate real-world conditions. Your implementation should handle these gracefully. + +## Project Structure + +``` +src/ +├── Entity/ # Domain entities (Doctor, Slot) +├── DoctorSlotsSynchronizer.php # Original code to refactor +└── StaticDoctorSlotsSynchronizer.php # Helper for testing + +# After refactoring, you might want to organize like: +src/ +├── Entity/ # Domain entities +├── Service/ # Business logic services +├── Repository/ # Data access layer +├── Vendor/ # Vendor API integrations +├── Exception/ # Custom exceptions +├── ValueObject/ # Value objects +└── ... +``` + +## Tips for Success + +1. **Start Small**: Begin with Phase 1 (refactoring), get tests passing, then move to Phase 2 +2. **Iterate**: Don't try to implement everything at once. Refactor, test, then add features +3. **Document as You Go**: Write comments and documentation while the context is fresh +4. **Use AI Wisely**: Let AI help with boilerplate, but make architectural decisions yourself +5. **Test Early**: Write tests as you refactor, not after +6. **Think About Production**: Consider how this would run in a real environment + +## Questions? + +If anything is unclear, don't hesitate to reach out. We value: +- Clear communication +- Thoughtful questions +- Understanding trade-offs +- Pragmatic solutions ## Good luck! + +We're excited to see what you build! 🚀