# Architecture

Harmony 3.0 separates customer conversation, locked business rules, integrations, and presentation so a flexible AI answer can never rewrite a price or booking rule.

## Request path

1. The browser requests a chat session from `/wp-json/harmony/v2/session`.
2. WordPress creates a UUID session, signs it with the site's nonce salt, and stores state in a 12-hour transient.
3. Each customer message is validated, rate-limited, stripped of HTML, and matched against the deterministic intake flow.
4. Obvious details supplied together are saved, while Harmony asks only the next missing question.
5. The service-area and quote engines apply locked rules after all required details are present.
6. The completed or review-required lead is written to the dedicated Harmony lead table.
7. Configured email, SMS, or webhook notifications run after the lead reaches a meaningful outcome.
8. OpenAI is optional and limited to short FAQ responses. It cannot calculate totals, confirm availability, or modify lead state.

## Data ownership

- Chat session state: WordPress transients, 12-hour expiration.
- Lead records: `{prefix}harmony_leads`.
- Settings and encrypted-at-rest behavior: standard WordPress options storage. Hosting-level database encryption is controlled by the host.
- Browser continuity: `sessionStorage`, which clears when the browser session ends.
- OpenAI API requests: `store=false`.

## Main modules

- `Harmony_Conversation`: flow orchestration.
- `Harmony_Parser`: validation and normalized lead fields.
- `Harmony_Service_Area`: approved location recognition.
- `Harmony_Quote_Engine`: deterministic prices and availability routing.
- `Harmony_OpenAI_Client`: optional FAQ answers.
- `Harmony_Leads`: persistence, search, export support, and retention.
- `Harmony_Notifications`: office email, customer email, Twilio, and webhooks.
- `Harmony_REST_Controller`: public API endpoints.
- `Harmony_Shortcode`: page and floating front ends.
- `Harmony_Admin`: settings and lead management.
- `Harmony_Privacy`: WordPress privacy tools.
