# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Architecture

This is a WordPress plugin that extends KiviCare healthcare management system with a comprehensive REST API. The plugin follows WordPress coding standards and uses modern PHP 8.1+ features with PSR-4 autoloading.

### Core Structure
- **Plugin Entry Point**: `src/care-api.php` - Main plugin file with WordPress headers and activation hooks
- **Initialization**: `src/includes/class-api-init.php` - Central coordinator for all API components
- **Endpoints**: `src/includes/endpoints/` - REST API endpoint handlers organized by entity type
- **Security**: `src/includes/class-security-manager.php` - JWT authentication and role-based access control
- **Admin Interface**: `src/admin/` - WordPress admin interface for API documentation

### API Architecture
The plugin implements a Master Orchestrator Supreme architecture pattern with:
- JWT authentication with refresh tokens
- Role-based access control for healthcare entities
- HIPAA-aware clinic data isolation
- Comprehensive audit logging and validation
- Enterprise-grade security measures

### Database Integration
Integrates with KiviCare's 35-table database schema covering:
- Patient management
- Doctor profiles and schedules
- Appointment scheduling
- Prescription management
- Billing and payment tracking
- Medical records and encounters

## Development Commands

### Testing
```bash
# Run all test suites
composer test

# Run specific test types
composer test:unit
composer test:integration
composer test:contract

# Run tests with coverage
composer test:coverage

# Setup WordPress test environment
composer setup:tests
```

### Code Quality
```bash
# Run code quality checks
composer quality

# Fix code quality issues automatically
composer quality:fix

# Run WordPress Coding Standards
composer phpcs

# Auto-fix coding standards violations
composer phpcbf
```

### PHPUnit Testing
The project uses PHPUnit 10+ with WordPress testing framework:
- Test bootstrap: `tests/bootstrap.php`
- Test suites: Contract, Integration, Unit, Performance
- WordPress test database configuration in `phpunit.xml`

### Build Scripts
Located in `bin/` directory:
- `install-wp-tests.sh` - Sets up WordPress test environment
- `code-quality.sh` - Comprehensive quality checks
- `run-tests.sh` - Test execution with different configurations

## WordPress Integration

### Plugin Activation
- Checks KiviCare plugin dependency
- Creates custom capabilities for healthcare roles
- Flushes rewrite rules for REST API routes

### Custom Capabilities
- `care_api_full_access` - Administrators
- `care_api_medical_access` - Doctors
- `care_api_patient_access` - Patients
- `care_api_reception_access` - Receptionists

### REST API Structure
Base URL: `/wp-json/care-api/v1/`
Endpoints organized by entity groups (appointments, patients, doctors, etc.)

## Testing Strategy

### Test Organization
- **Contract Tests**: API endpoint contracts and response validation
- **Integration Tests**: Database operations and WordPress integration
- **Unit Tests**: Individual class and method testing
- **Performance Tests**: Load testing and optimization validation

### Test Database
Uses isolated WordPress test database with KiviCare schema
Configuration handled through `phpunit.xml` server variables

## Dependencies

### Production
- PHP 8.1+
- WordPress 6.0+
- KiviCare plugin (required dependency)
- firebase/php-jwt for JWT authentication

### Development
- PHPUnit 10+ for testing
- WordPress Coding Standards (WPCS)
- PHP_CodeSniffer for code quality
- WP-CLI for WordPress operations

## Security Considerations

The plugin implements healthcare-grade security:
- JWT tokens with expiration and refresh
- Role-based access control
- Clinic data isolation
- Input validation and sanitization
- Audit logging for compliance
- OWASP security compliance