care-api/CLAUDE.md

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

# 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

# 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