# AI Content Writer & Auto Post Generator — Architecture

**Plugin slug:** `ai-text-block`  
**Current version:** 4.1.0  
**Text domain:** `rapidtextai`

---

## File Structure

```
ai-text-block/
├── rapidtext-ai-text-block.php        # Main plugin bootstrap file
├── rapidtext-ai-meta-box.php          # Post/page editor meta box
├── rapidtext-ai-check.php             # API usage/limit check & admin notices
├── rapidtextai-openaihandler.php      # OpenAI-compatible AJAX handlers (excerpt, tags, taxonomy, generate post)
├── readme.txt
│
├── admin/
│   ├── settings.php                   # Settings page view (API key auth + feature cards)
│   ├── auto_blogging_page.php         # Campaign editor form view
│   └── auto_blogging_campaigns.php    # Campaigns list view
│
├── assets/
│   ├── css/
│   │   ├── admin.css                  # Admin panel styles
│   │   ├── metabox.css                # Post editor meta box styles
│   │   └── rapidtextai-styles.css     # General plugin styles
│   ├── js/
│   │   ├── rapidtextai.js             # Core meta box JS (content generation)
│   │   ├── metabox.js                 # Meta box entry point / React mount (module)
│   │   ├── admin.js                   # Excerpt generation UI
│   │   ├── tags.js                    # Tags & categories generation UI
│   │   ├── featured.js                # Featured image generation UI
│   │   └── marked.min.js              # Markdown renderer (v4.3.0)
│   └── icons/
│       └── menu.svg                   # Admin menu icon
│
├── block/
│   └── rapidtextai-block.js           # Gutenberg block editor script
│
├── ext/
│   └── chatbots/
│       ├── chatbots.php               # Chatbots module (admin UI, DB, AJAX, shortcode)
│       ├── css/
│       │   ├── chatbots-admin.css
│       │   └── chatbots-frontend.css
│       ├── js/
│       │   ├── chatbots-admin.js
│       │   └── chatbots-frontend.js
│       └── views/
│           ├── chatbot-form.php       # Add/edit chatbot form view
│           ├── chatbot-widget.php     # Frontend widget/embed view
│           └── ai-chatbot-json-examples.md
│
├── languages/                         # i18n translation files (.pot / .po / .mo)
│
└── docs/
    └── architech.md                   # This file
```

---

## Database Structure

### Custom Table — `{prefix}rapidtextai_chatbots`

Created lazily via `dbDelta()` on first access and on plugin activation.

| Column            | Type              | Notes                                    |
|-------------------|-------------------|------------------------------------------|
| `id`              | mediumint(9) PK   | Auto increment                           |
| `name`            | varchar(255)      | Chatbot display name                     |
| `description`     | text              | Optional description                     |
| `model`           | varchar(100)      | AI model identifier (e.g. `gpt-4`)       |
| `theme`           | varchar(50)       | UI theme                                 |
| `status`          | varchar(20)       | `active` \| `inactive`; default `active` |
| `system_message`  | text              | System prompt                            |
| `welcome_message` | text              | Opening message shown to users           |
| `settings`        | longtext          | JSON blob (temperature, max_tokens, …)   |
| `knowledge_base`  | longtext          | JSON blob of KB entries                  |
| `tools`           | longtext          | JSON blob of function-call tool configs  |
| `created_at`      | datetime          | Default `CURRENT_TIMESTAMP`              |
| `updated_at`      | datetime          | Default `CURRENT_TIMESTAMP`              |

### WordPress Options (wp_options)

| Option key                            | Type            | Description                                          |
|---------------------------------------|-----------------|------------------------------------------------------|
| `rapidtextai_api_key`                 | string          | RapidTextAI API key                                  |
| `rapidtextai_auto_blogging_campaigns` | serialized array| Array of campaign objects (see Campaign structure)   |
| `rapidtextai_auto_blogging`           | serialized array| Legacy single-campaign settings (pre-4.0, migrated) |
| `rapidtextai_campaigns_migrated`      | bool            | Migration flag (legacy → multi-campaign)             |
| `rapidtextai_whats_new_dismissed`     | string          | Version string of last-dismissed "What's New" notice |

#### Campaign Object Structure (stored in `rapidtextai_auto_blogging_campaigns`)

```php
[
  'id'          => string,   // Unique campaign ID
  'name'        => string,   // Display name
  'enabled'     => bool,
  'schedule'    => string,   // 'hourly' | 'twicedaily' | 'daily' | 'weekly'
  'post_status' => string,   // 'publish' | 'draft' | 'pending'
  'post_author' => int,      // WP user ID
  'model'       => string,   // AI model slug
  'tone'        => string,   // 'informative' | 'conversational' | 'formal' | 'friendly' | 'persuasive'
  'topics'      => string,   // Newline-separated topic strings
  'categories'  => array,    // WP category IDs
  'created'     => string,   // Date string
]
```

### Transients

| Transient key              | TTL    | Description                                  |
|----------------------------|--------|----------------------------------------------|
| `rapidtextai_usage_check`  | 1 hour | Throttles API usage-check calls per pageload |

---

## Admin Pages & Menus

### Top-level menu — `RapidTextAI` (`rapidtextai-settings`)

Registered via `admin_menu` → `rapidtextai_settings_menu()`

- **Callback file:** `admin/settings.php`
- Shows API key authentication form
- Shows feature cards (AI Chatbots, Auto Blogging, Add New Post, Chrome Extension, Mobile App, AI Chat Interface) when authenticated

### Sub-menu — `Auto Blogging` (`rapidtextai-auto-blogging`)

Registered inside `rapidtextai_auto_blogging_menu()` on `admin_menu`

- **List view:** `admin/auto_blogging_campaigns.php`
- **Editor view:** `admin/auto_blogging_page.php`
- Handles campaign CRUD (create, edit, toggle enable/disable, delete) via GET params + nonce-verified POST

### Sub-menu — `AI Chatbots` (`rapidtextai-chatbots`)

Registered in `ext/chatbots/chatbots.php` → `rapidtextai_add_chatbots_menu()` on `admin_menu` (priority 999)

- **List view:** inline in `rapidtextai_chatbots_list_page()`
- **Add/Edit view:** `ext/chatbots/views/chatbot-form.php`
- Supports: name, model, theme, status, system message, welcome message, settings, knowledge base, tools

---

## Meta Box / Generate Article Modal

> **Note:** The meta box registration is intentionally disabled. The UI is delivered via a fullscreen modal triggered by a "Generate Article" button injected into the Featured Image sidebar box.

**Trigger button ID:** `#rapidtextai-generate-btn`  
**Button placement:** Appended inside `#postimagediv .inside`; falls back to after `#submitdiv`  
**Button style:** Blue (`#2271b1`), full-width, icon from `https://app.rapidtextai.com/assets/images/fav.png?v=1.1`

**Modal IDs:**
- `#rapidtextai-modal-overlay` — fixed-position backdrop
- `#rapidtextai-modal-wrap` — centered dialog (max-width 900px, max-height 90vh)
- `#rapidtextai-modal-header` — title bar with close button
- `#rapidtextai-modal-body` — scrollable content area containing `#rapidtextai-root`

**Modal open/close:** `.rtai-open` class toggled on overlay; also closed on backdrop click or `Escape` key  
**Rendered via:** `admin_footer` → `rapidtextai_render_generate_modal()` (added inside `rapidtextai_metabox_enqueue_scripts()`)  
**Defined in:** `rapidtext-ai-meta-box.php`

### React UI

Mount point: `<div id="rapidtextai-root">` (inside modal body)  
Entry script: `assets/js/metabox.js` (loaded as `<script type="module">` in admin footer)

### Conditionally enqueued scripts (on `post.php` / `post-new.php`)

| Script handle                       | File                    | Condition                                 |
|-------------------------------------|-------------------------|-------------------------------------------|
| `rapidtextai_script`                | `assets/js/rapidtextai.js` | Always                                 |
| `rapidtextai_marked_js`             | `assets/js/marked.min.js`  | Always                                 |
| `rapidtextai_script-admin-js`       | `assets/js/admin.js`       | Post type supports `excerpt`           |
| `rapidtextai_script-tags-js`        | `assets/js/tags.js`        | Post type supports `post_tag`/`category` or is `post` |
| `rapidtextai_script-featured-js`    | `assets/js/featured.js`    | Post type supports `thumbnail`         |

### Localized data (`rapidtextai_ajax`)

```js
{
  ajax_url: string,   // admin-ajax.php URL (https-aware)
  nonce:    string,   // wp_create_nonce('rapidtextai_nonce')
  api_key:  string    // rapidtextai_api_key option value
}
```

---

## Gutenberg Block

**Block name:** `rapidtextai/ai-text-block`  
**Script:** `block/rapidtextai-block.js`  
**Dependencies:** `wp-blocks`, `wp-element`, `wp-editor`  
**Registered via:** `init` → `rapidtextai_register_gutenberg_block()`

---

## Shortcodes

| Shortcode                                        | Handler function                           | File                          |
|--------------------------------------------------|--------------------------------------------|-------------------------------|
| `[rapidtextai_ai_text_block]`                    | `rapidtextai_ai_text_block_shortcode()`    | `rapidtext-ai-text-block.php` |
| `[rapidtextai_chatbot id="X"]`                   | `rapidtextai_chatbot_shortcode()`          | `ext/chatbots/chatbots.php`   |

WP Bakery shortcode `rapidtextai_ai_text_block` is also registered via `vc_map()` when WPBakery is active.

---

## Cron Jobs

### Per-campaign dynamic hooks

Each enabled Auto Blogging campaign registers its own cron hook:

| Hook name pattern                             | Callback                              | Schedules              |
|-----------------------------------------------|---------------------------------------|------------------------|
| `rapidtextai_auto_blogging_cron_{campaign_id}`| `rapidtextai_generate_auto_blog_post()` | hourly / twicedaily / daily / weekly |

- Scheduled with `wp_schedule_event()` in `rapidtextai_schedule_campaign_cron()`
- Cleared with `wp_clear_scheduled_hook()` on campaign disable/delete and plugin deactivation
- All campaign cron hooks are re-registered on `plugins_loaded` via `rapidtextai_register_campaign_cron_hooks()` so they survive page loads

### Legacy global hook (pre-4.0 migration support)

| Hook name                       | Callback                              | Note                            |
|---------------------------------|---------------------------------------|---------------------------------|
| `rapidtextai_auto_blogging_cron`| `rapidtextai_generate_auto_blog_post()` | Old single-campaign hook; migrated to per-campaign hooks |

### Activation / Deactivation

| Hook                             | Function                              |
|----------------------------------|---------------------------------------|
| `register_activation_hook`       | `rapidtextai_activate_auto_blogging()`  |
| `register_deactivation_hook`     | `rapidtextai_deactivate_auto_blogging()` — clears all scheduled cron hooks |

---

## AJAX Handlers

All handlers use nonce `rapidtextai_nonce` unless noted.

### Content Generation (meta box)

| Action                                    | Auth     | Handler                                      | Description                                          |
|-------------------------------------------|----------|----------------------------------------------|------------------------------------------------------|
| `rapidtextai_generate_article`            | priv     | `rapidtextai_generate_article()`             | Non-streaming article generation                     |
| `rapidtextai_generate_article_stream`     | priv     | `rapidtextai_generate_article_stream()`      | SSE streaming article generation via cURL            |
| `rapidtextai_generate_content`            | priv+nopriv | `rapidtextai_generate_content_callback()` | Generate content for front-end block instances       |
| `rapidtextai_generate_content_block`      | priv+nopriv | `rapidtextai_generate_content_callback_block()` | Generate content via Gutenberg block        |

### Post Meta Helpers (rapidtextai-openaihandler.php)

| Action                                    | Auth         | Description                                               |
|-------------------------------------------|--------------|-----------------------------------------------------------|
| `rapidtextai_get_excerpt`                 | priv+nopriv  | Generate excerpt from post content via GPT-3.5-turbo      |
| `rapidtextai_get_tags`                    | priv+nopriv  | Generate tags & categories, insert into WP terms          |
| `rapidtextai_get_taxonomy_terms`          | priv+nopriv  | Generate terms for any given taxonomy                     |

### Settings

| Action                          | Auth  | Handler                      | Description            |
|---------------------------------|-------|------------------------------|------------------------|
| `rapidtextai_save_api_key`      | priv  | `rapidtextai_save_api_key()` | Save API key to options |

### Auto Blogging

| Action                           | Auth     | Handler                             | Description                              |
|----------------------------------|----------|-------------------------------------|------------------------------------------|
| `rapidtextai_improve_topics`     | priv+nopriv | `rapidtextai_improve_topics_callback()` | AI-improve topic list before save    |
| `rapidtextai_get_featured_image` | priv+nopriv | `rapidtextai_get_featured_image_for_topic()` | Search & return featured image URL |
| `rapidtextai_upload_image_from_url` | priv+nopriv | `rapidtextai_upload_image_from_url_callback()` | Upload remote image to WP media library |

### Logging & Usage

| Action                      | Auth  | Handler                            | Description                  |
|-----------------------------|-------|------------------------------------|------------------------------|
| `rapidtextai_get_logs`      | priv  | `rapidtextai_get_logs_callback()`  | Retrieve cron/generation logs |
| `rapidtextai_clear_logs`    | priv  | `rapidtextai_clear_logs_callback()`| Clear logs                    |
| `rapidtextai_get_usage_data`| priv  | `rapidtextai_get_usage_data_callback()` | Fetch usage stats from API |

### Chatbots (ext/chatbots/chatbots.php) — nonce `rapidtextai_chatbots_nonce`

| Action                            | Auth         | Handler                               | Description                        |
|-----------------------------------|--------------|---------------------------------------|------------------------------------|
| `rapidtextai_get_models`          | priv         | `rapidtextai_get_models_callback()`   | Fetch available AI models from API |
| `rapidtextai_chatbot_message`     | priv+nopriv  | `rapidtextai_chatbot_message_callback()` | Process user chat message       |

Frontend chatbot uses nonce `rapidtextai_chatbots_frontend_nonce`.

---

## API Endpoint

All AI calls proxy through the RapidTextAI platform:

```
https://app.rapidtextai.com/openai/v1/chat/completions?gigsixkey={api_key}
https://app.rapidtextai.com/openai/v1/chat/completionsarticle?gigsixkey={api_key}
https://app.rapidtextai.com/openai/v1/chat/completionsarticle-stream?gigsixkey={api_key}
https://app.rapidtextai.com/openai/v1/models?gigsixkey={api_key}
https://app.rapidtextai.com/api.php?gigsixkey={api_key}    ← usage check
```

---

## Auto Blogging — 4-Step Agent Mode Pipeline

When Agent Mode is selected, each post goes through:

1. **Draft Generation** — Full article draft via SSE streaming  
2. **Polish & Publish** — Removes placeholders, enforces professional tone  
3. **Heading Optimization** — Generates specific image-search queries per heading  
4. **Final Assembly** — Inserts contextually relevant images, sets featured image, assigns tags, publishes  

---

## Supported AI Models

| Model slug              | Provider     |
|-------------------------|--------------|
| `gemini-2.0-flash`      | Google       |
| `gemini-2.5-flash`      | Google       |
| `deepseek-chat`         | DeepSeek     |
| `deepseek-v4-flash`     | DeepSeek     |
| `deepseek-v4-pro`       | DeepSeek     |
| `claude-3-7-sonnet-latest` | Anthropic |
| `gpt-5`                 | OpenAI       |
| `gpt-4`                 | OpenAI       |
| `gpt-3.5-turbo`         | OpenAI       |
| `grok-3`                | xAI          |
| `glm-4.6v-flash`        | Zhipu AI     |