# CLAUDE.md

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

## Build Commands

```bash
# Install dependencies
yarn                        # JavaScript/TypeScript dependencies
composer install            # PHP dependencies (for linting)

# Development
yarn start                  # Watch mode - compiles assets on change

# Build
yarn build                  # Full build (typecheck + compile)
yarn typecheck              # TypeScript type checking only
yarn bundle                 # Build + create plugin ZIP

# Linting
./vendor/bin/phpcs          # PHP CodeSniffer (WordPress standards)
./vendor/bin/phpcs -n -p    # PHP linting (no warnings, progress)
```

## Architecture Overview

This is a WordPress plugin that integrates AI-powered publishing tools. It uses a hybrid architecture:

**Backend (PHP):** Object-oriented PHP with WordPress hooks system
**Frontend (TypeScript/React):** Modern React with @wordpress/scripts bundling

### Plugin Initialization Flow

```
nota-wordpress-plugin.php (entry point)
    ↓ plugins_loaded hook
Nota::instance() (singleton in includes/class-nota.php)
    ↓ Creates all services via dependency injection
    ├── Nota_Settings - Plugin configuration
    ├── Nota_Api - External API client
    ├── Nota_WP_Rest - AJAX request router
    ├── Nota_Post_Tools - Post editor integration
    ├── Nota_Script - DRAFT article tool
    ├── Nota_News - News recommendations
    └── Nota_Dashboard - Admin dashboard
```

### React Entry Points

Four separate bundles compiled to `/dist/app/`:

| Entry         | File                         | Purpose                        |
| ------------- | ---------------------------- | ------------------------------ |
| postTools     | `assets/js/postTools.ts`     | Post editor meta box & sidebar |
| notaScript    | `assets/js/notaScript.ts`    | DRAFT article generation tool  |
| notaNews      | `assets/js/notaNews.ts`      | News recommendations UI        |
| dashboardPage | `assets/js/dashboardPage.ts` | Main admin dashboard           |

### Frontend-Backend Communication

All AJAX routes through a single endpoint:

```
Frontend (React) → POST wp-admin/admin-ajax.php?action=nota_action
    ↓
Nota_WP_Rest::handle_action() → Routes to service methods → JSON response
```

Frontend services are in `assets/js/services/notaService/` - each function makes requests via the shared fetch utility.

### State Management

- **WordPress Data Store** (`assets/js/data/`): Redux store for post metadata, grades, brands, tones
- **React Query**: Server state caching via `@tanstack/react-query`

### Styling

Tailwind CSS with `ntw-` prefix to avoid WordPress conflicts. All utilities scoped under `.nota` class for specificity.

## Key Directories

```
includes/           # PHP classes (Nota_* naming convention)
assets/js/
  ├── components/   # React components
  ├── hooks/        # Custom React hooks
  ├── services/     # API service layer
  ├── utils/        # Shared utilities
  └── data/         # WordPress Redux store
templates/admin/    # PHP admin templates
dist/               # Compiled output (not committed)
```

## PHP Class Naming

All PHP classes follow `Nota_*` convention with files named `class-nota-*.php`. Key classes:

- `Nota` - Main singleton orchestrator
- `Nota_Api` - HTTP client for external Nota API
- `Nota_WP_Rest` - Central AJAX handler
- `Nota_Settings` - Options API wrapper
- `Nota_Post_Tools` - Post editor meta box
- `Nota_Migrations` - Database schema versioning

## Code Standards

**PHP:** WordPress Coding Standards via PHPCS (WordPress-Extra, WordPress-VIP-Go)
**TypeScript:** ESLint with @wordpress/eslint-plugin, Prettier
**Pre-commit:** Husky runs lint-staged on staged files

## Local Development

Configure `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_NOTA_API_URL', 'http://localhost:3010/');
```

Plugin settings at WordPress admin → Settings → Nota Tools (API key, URL, timeout).