# MyEP Next Booking - Documentation Index

This directory contains comprehensive documentation for the MyEP Next Booking system architecture, implementation guides, and development workflows.

## 📋 Documentation Overview

### Core Architecture Documentation

#### [FIELD_STATE_SYSTEM.md](FIELD_STATE_SYSTEM.md)
**Universal Conditional Field State System**
- Comprehensive guide to the conditional field architecture
- Field state providers, conditions, and composite logic
- HTMX integration for real-time field updates
- Examples for age-based, value-dependent, and complex conditions
- **Status**: ✅ Current and complete

#### [FORM_PROCESSING.md](FORM_PROCESSING.md)
**Advanced Form Processing Architecture**
- Field handler system with dependency resolution
- DTO pattern implementation for type-safe data flow
- Service registration and field option providers
- HTMX dynamic updates and form validation
- **Status**: ✅ Current with recent HTMX fixes

#### [PRICING_DISPLAY_IMPLEMENTATION.md](PRICING_DISPLAY_IMPLEMENTATION.md)
**Real-time Pricing System**
- Inline pricing in form options with smart formatting
- Unified booking summary with integrated pricing display
- Service pricing calculations and HTMX integration
- Implementation details and UX improvements
- **Status**: ✅ Implementation completed successfully

#### [SERVICE_AVAILABILITY_SYSTEM.md](SERVICE_AVAILABILITY_SYSTEM.md)
**Dynamic Service Availability System**
- Prevents overbooking within single booking sessions
- Real-time availability tracking across all participants
- Dynamic service filtering based on capacity limits
- Seamless HTMX integration for instant updates
- **Status**: ✅ Implementation completed successfully

### Feature Implementation Guides

#### [TRANSPORTATION_SERVICES_IMPLEMENTATION_PLAN.md](TRANSPORTATION_SERVICES_IMPLEMENTATION_PLAN.md)
**Comprehensive Transportation Services**
- Transportation type selection (bus vs. car)
- Pickup services with location-based options
- Parking services for self-organized transport
- Direction mapping system and field handlers
- **Status**: ✅ Fully implemented and tested

#### [AGE_BASED_FIELDS_PLAN.md](AGE_BASED_FIELDS_PLAN.md)
**Age-Based Field Constraints System**
- Age range conditions for field visibility/behavior
- Service filtering based on participant age
- Dynamic field state management
- Implementation roadmap and examples
- **Status**: 🔄 Planned implementation

#### [AGE_CONSTRAINTS_MODEL_EXTENSION_PLAN.md](AGE_CONSTRAINTS_MODEL_EXTENSION_PLAN.md)
**Extended Age Constraint Model**
- Advanced age-based business logic
- Service availability constraints
- Field interdependency handling
- Data model extensions
- **Status**: 🔄 Planning phase

### Development & Maintenance

#### [DOCUMENTATION_UPDATES_2025-09-02.md](DOCUMENTATION_UPDATES_2025-09-02.md)
**Recent Documentation Updates**
- Comprehensive record of HTMX service selection bug fixes
- Pricing implementation completion status
- Field handler improvements and technical debt resolution
- Benefits achieved and next steps
- **Status**: ✅ Historical record of completed improvements

## 🏗️ System Architecture Overview

### Multi-Step Booking Flow
1. **Step 1**: Room selection with dynamic pricing
2. **Step 2**: Participant details with conditional fields
3. **Step 3**: Confirmation and BPN API submission

### Core Components

#### Form System Architecture
- **Field Handlers**: Modular field processing with dependency chains
- **Conditional States**: Dynamic field behavior (readonly, disabled, hidden, required)
- **Service Integration**: Real-time updates via HTMX
- **Pricing Display**: Inline costs and unified summary

#### BusProNet Integration
- **XML API Client**: Request/response handling
- **Data Processing**: API response transformation
- **Caching Layer**: Performance optimization
- **Error Handling**: Comprehensive error management

#### Service Layer
- **Booking Management**: Core workflow orchestration
- **Travel Data Services**: API data access and caching
- **Pricing Calculations**: Real-time cost computation
- **Field Options**: Dynamic choice generation

## 🎯 Feature Status Matrix

| Feature | Planning | Implementation | Testing | Completed |
|---------|----------|---------------|---------|-----------|
| **Multi-Step Booking** | ✅ | ✅ | ✅ | ✅ |
| **Room Selection** | ✅ | ✅ | ✅ | ✅ |
| **Service Selection** | ✅ | ✅ | ✅ | ✅ |
| **Pricing Display** | ✅ | ✅ | ✅ | ✅ |
| **Transportation Services** | ✅ | ✅ | ✅ | ✅ |
| **Conditional Field States** | ✅ | ✅ | ✅ | ✅ |
| **HTMX Integration** | ✅ | ✅ | ✅ | ✅ |
| **BPN API Integration** | ✅ | ✅ | ✅ | ✅ |
| **Dynamic Availability System** | ✅ | ✅ | ✅ | ✅ |
| **Service Descriptions** | ✅ | ✅ | ✅ | ✅ |
| **License Plate Field** | ✅ | ✅ | ✅ | ✅ |
| **Age-Based Constraints** | ✅ | 🔄 | ⏳ | ⏳ |
| **Advanced Pricing** | ✅ | ⏳ | ⏳ | ⏳ |

**Legend**: ✅ Complete | 🔄 In Progress | ⏳ Planned

## 🔧 Implementation Patterns

### Field Handler Pattern
```php
class ParticipantTransportationOutboundFieldHandler extends AbstractParticipantFieldHandler
{
    public function getFieldName(): string { return 'transportationOutbound'; }
    public function getDependencies(): array { return ['assignedRoomId']; }
    public function shouldProcess(/* ... */): bool { /* conditional logic */ }
    public function processField(/* ... */): void { /* field processing */ }
}
```

### Conditional Field States
```php
$this->fieldStateConditions['advancedServices'] = [
    'hidden' => new AgeRangeCondition(null, 15),
    'required' => FieldValueCondition::equals('roomType', 'suite'),
];
```

### Service Registration
```php
# config/services.yaml
App\Form\Service\ParticipantTransportationOutboundFieldHandler:
    tags: [{ name: 'app.participant_field_handler', priority: 100 }]

App\Service\ServiceAvailabilityCalculator:
    # Automatically registered via autowiring
```

## 🧪 Testing Strategy

### Test Coverage Areas
- **Unit Tests**: Service layer and business logic
- **Integration Tests**: Form processing and API communication
- **Field Handler Tests**: Conditional logic and dependencies
- **XML Processing Tests**: BPN API response parsing

### Test Commands
```bash
# All tests
./vendor/bin/phpunit

# Specific areas
./vendor/bin/phpunit tests/Service/          # Service layer
./vendor/bin/phpunit tests/BusProNet/        # API integration
./vendor/bin/phpunit tests/Form/             # Form processing

# Test availability system
bin/console debug:container ServiceAvailabilityCalculator
```

## 📈 Performance Considerations

### Optimization Strategies
- **Lazy Loading**: Field handlers loaded on demand
- **Caching**: API responses and computed choices
- **Dependency Tracking**: Efficient field state updates
- **HTMX Optimization**: Targeted DOM updates

### Monitoring Points
- Form rendering performance
- HTMX response times
- BPN API communication latency
- Database query optimization
- Service availability calculation performance

## 🔄 Development Workflow

### Adding New Features

1. **Plan**: Create implementation plan document
2. **Design**: Define interfaces and data structures
3. **Implement**: Follow established patterns
4. **Test**: Unit and integration testing
5. **Document**: Update relevant documentation
6. **Deploy**: Production deployment with monitoring

### Code Standards
- PSR-12 compliance with `declare(strict_types=1)`
- PHP 8+ features (typed properties, constructor promotion)
- Immutable DateTime objects
- Explicit comparisons and type safety
- Comprehensive documentation

## 📚 Related Resources

### External Documentation
- [Symfony 6.4 Documentation](https://symfony.com/doc/6.4/index.html)
- [HTMX Documentation](https://htmx.org/docs/)
- [TailwindCSS Documentation](https://tailwindcss.com/docs)
- [Stimulus Handbook](https://stimulus.hotwired.dev/handbook/introduction)

### Project-Specific Guides
- **[../CLAUDE.md](../CLAUDE.md)**: AI development assistance guidelines
- **Installation & Setup**: See main README.md
- **API Integration**: BusProNet XML API documentation (internal)
- **Deployment**: Production deployment procedures (internal)

## 🎯 Future Roadmap

### Planned Enhancements
- **Age-Based Field Constraints**: Complete implementation
- **Advanced Pricing Features**: Discounts, taxes, multi-currency
- **Enhanced BPN Integration**: Extended API coverage
- **Mobile Optimization**: Responsive design improvements
- **Analytics Integration**: User behavior tracking
- **Cross-Session Availability**: Extend availability tracking beyond single sessions
- **API Availability Validation**: Implement final validation stage against BusProNet API before booking confirmation

### Technical Debt
- **Code Coverage**: Increase test coverage to 90%+
- **Performance Optimization**: Form rendering improvements
- **Documentation**: API endpoint documentation
- **Monitoring**: Enhanced logging and metrics
- **Availability Testing**: Comprehensive test coverage for availability system
- **API Validation Integration**: Implement real-time availability validation via BusProNet API

---

**Documentation Maintained By**: Development Team  
**Last Updated**: 2025-01-XX  
**Version**: 2.0  
**Status**: ✅ Current and Comprehensive

For development assistance, see [CLAUDE.md](../CLAUDE.md) for AI-specific guidelines and project context.