> ## Documentation Index
> Fetch the complete documentation index at: https://docs.woopilot.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> How WooPilot AI achieves sub-10ms response times, 100% mutation safety, and strict CQRS routing

# Enterprise Architecture & CQRS Principles 🏛️

WooPilot AI is engineered with a **Strict CQRS (Command Query Responsibility Segregation)** design, separating read-only analytical queries from store-mutating commands.

```text theme={null}
┌─────────────────────────────────────────────────────────────────────────────┐
│                           HEXAGONAL CLOUD ARCHITECTURE                      │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
            ┌──────────────────────────┼──────────────────────────┐
            ▼                          ▼                          ▼
   [ Telegram UX / TMA ]      [ Cloud Core Gateway ]     [ WordPress Bridge ]
   • grammY Bot Framework     • 6-Layer Prompt Engine    • Edge Event Engine
   • React 18 Mini Apps       • Multi-Step Agentic Loop  • Read-Only $wpdb Guard
   • Touch-First Ergonomics   • PostgreSQL & Redis Vault • In-Memory rest_do_request
```

***

## 🛠️ The 4 Consolidated CQRS Tools

Rather than overloading the AI model with dozens of overlapping API tools (which causes token bloat and routing confusion), WooPilot AI equips the LLM with **4 deterministic CQRS tools**:

| Tool Identifier                  |       Category       | Primary Use Case                                                                                                              | Output Destination                |
| :------------------------------- | :------------------: | :---------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| **`execute_read_only_sql`**      |        `READ`        | Fast analytical aggregates (`SUM`, `COUNT`, `AVG`), KPIs, and short leaderboards ($\le 5\text{–}10$ rows).                    | Formatted text in Telegram chat   |
| **`render_infographic`**         |    `PRESENTATION`    | High-contrast visual dashboards (summaries, trend dynamics, category shares, funnels).                                        | Retina PNG image in Telegram chat |
| **`create_table_artifact`**      |      `ARTIFACT`      | Interactive web tables and smart trend charts for deep datasets ($> 10$ rows).                                                | Telegram Mini App (TMA)           |
| **`create_diff_table_artifact`** | `STAGING / MUTATING` | Universal Staging and 1-click batch mutation gateway for 100% store changes (prices, stock, statuses, coupons, descriptions). | TMA Visual Diff (`~~Old~~ ➔ New`) |

***

## 🧠 6-Layer KV-Cached Prompt Assembly Engine

To achieve lightning-fast response times and minimize AI costs, `cloud-core` structures its context into **6 decoupled prompt layers**:

1. **Layer 1 (System Core):** Immutable safety invariants, tool execution rules, and CQRS directives (100% static).
2. **Layer 2 (Store Metadata):** Store name, currency symbol, timezone, WooCommerce version, and HPOS mode (cached for 24h).
3. **Layer 3 (DDL Schema Manifest):** Introspected MySQL schema, table prefixes, and HPOS lookup mappings (cached for 24h).
4. **Layer 4 (Static Daily Date Anchor):** Daily reference date (`YYYY-MM-DD 00:00:00`) preserving byte-identical prefix caching.
5. **Layer 5 (Sliding Window Memory):** Last 10 conversation turns from Redis.
6. **Layer 6 (Custom Tone of Voice & User Query):** Merchant-defined Tone of Voice rules + dynamic local store clock injected at the bottom.

<Tip>
  By pinning Layers 1 through 4 into a static prefix, WooPilot AI leverages modern LLM KV-caching (DeepSeek / Anthropic / OpenAI), saving **up to 85% in latency and prompt costs**.
</Tip>

***

## ⚡ "Compile Once, Execute at Edge" (WooAuto)

When merchants create event-driven automations, WooPilot AI does not execute slow, expensive LLM calls during live customer checkout sessions.

1. **Compilation in Cloud:** The user's natural language instruction is translated by the LLM into a deterministic **AST JSON Blueprint**.
2. **Edge Execution in WordPress:** The blueprint is saved directly in WordPress memory (`autoload = true`). When native WooCommerce hooks fire (`woocommerce_checkout_order_created`), WordPress executes the condition tree in native PHP with **0ms network latency and \$0 AI token costs**.


## Related topics

- [Scheduled AI Scenarios](/wooauto/scheduled-scenarios.md)
- [Telegram Mini App (TMA) Suite](/tma/overview.md)
- [Frequently Asked Questions](/faq.md)
- [Introduction](/introduction.md)