diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..aa21294
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a WordPress/WooCommerce plugin that integrates with the Miravia marketplace (owned by Alibaba). The plugin allows merchants to:
+- Upload WooCommerce products to Miravia
+- Download orders from Miravia
+- Manage product synchronization between platforms
+- Handle multiple Miravia accounts and profiles
+
+## Architecture
+
+### Core Components
+
+**Main Plugin File**: `connector-miravia/connector-miravia.php`
+- Entry point that defines plugin metadata and initializes the MiraviaWOO class
+- Sets up WordPress hooks and admin menu structure
+- Loads all required class dependencies
+
+**Class Structure**:
+- `class.core.php` - Core functionality for accounts, profiles, and database operations
+- `class.api.php` - AJAX handlers for all Miravia API interactions
+- `class.product.php` - WooCommerce product management and synchronization
+- `class.order.php` - Miravia order processing and WooCommerce integration
+- `class.categories.php` - Category mapping between WooCommerce and Miravia
+- `class.db.php` - Database schema management and installation
+
+**Shared Classes** (in `classes/shared/`):
+- `MiraviaProduct.php` - Product data structure for Miravia API
+- `MiraviaCombination.php` - Product variations/SKUs handling
+- `MiraviaCategory.php`, `MiraviaFilter.php`, `MiraviaFeed.php` - Support classes
+
+### Database Schema
+
+The plugin creates custom tables:
+- `{prefix}_miravia_accounts` - Stores Miravia seller account credentials
+- `{prefix}_miravia_profiles` - Product upload profiles with mapping rules
+- `{prefix}_miravia_products` - Synchronization status between WooCommerce and Miravia
+- `{prefix}_miravia_orders` - Order tracking and fulfillment data
+
+### Key Features
+
+**Product Upload**:
+- Products are uploaded via profiles that define category mappings and filters
+- Images must be formatted as `{"Image": [...]}` structure for Miravia API compliance
+- Support for both simple products and variations
+
+**Order Management**:
+- Downloads orders from Miravia and creates corresponding WooCommerce orders
+- Tracks order status and fulfillment
+- Handles shipping label generation
+
+**Multi-Account Support**:
+- Multiple Miravia seller accounts can be configured
+- Each profile can be associated with specific accounts
+
+## Development Commands
+
+### Deployment
+- **Deploy changes**: `./deploy_miravia.sh` - Automated git deployment script that commits and pushes changes
+
+### No Build Process
+This is a pure PHP WordPress plugin with no build step required. Changes are deployed directly.
+
+### Testing
+No automated test framework is configured. Testing should be done manually in a WordPress/WooCommerce environment.
+
+## Important Implementation Notes
+
+### API Integration
+- All Miravia API calls go through the WeComm proxy server
+- Authentication uses tokens stored in the accounts table
+- Product images must follow specific structure: `Images: {"Image": [...]}`
+
+### WordPress Integration
+- Uses standard WordPress hooks and filters
+- Admin interface is built with WordPress admin styles
+- Internationalization support with 'miraviawoo' text domain
+
+### Error Handling
+- Logging is handled through custom LOG class
+- Debug mode can be enabled via WordPress options
+- Errors are stored in product sync records for troubleshooting
+
+### Security Considerations
+- All database operations use WordPress $wpdb for SQL injection protection
+- User capability checks (`manage_woocommerce`, `manage_options`)
+- Input sanitization with WordPress functions
+- Nonce verification for admin actions
\ No newline at end of file