> For the complete documentation index, see [llms.txt](https://docs.xenoraa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xenoraa.com/xenoraa-changelog-and-architecture/key-coding-patterns-and-rules-14.md).

# Key Coding Patterns & Rules

> These rules are enforced across all Xenoraa development. Every AI agent and developer must follow them.

***

## Main Controllers

| Controller                     | Responsibility                                       |
| ------------------------------ | ---------------------------------------------------- |
| `CrmModuleController.php`      | Handles ALL CRM2 + Inventory + POS + Settings routes |
| `AccountsController.php`       | Finance module (income, expenses, reports, payroll)  |
| `PosController.php`            | POS terminal, sessions, receipts                     |
| `DashboardController.php`      | Main tenant dashboard                                |
| `EcommerceController.php`      | Online store, orders, coupons                        |
| `XenaController.php`           | Xena AI chat, streaming SSE, tool dispatch           |
| `XenaApiController.php`        | ChatGPT Actions API (Bearer token auth)              |
| `SuperAdminXenaController.php` | Super admin Xena management panel                    |

***

## PostgreSQL Rules

All queries must use PostgreSQL-compatible syntax. The following MySQL-isms are **forbidden**:

* Use `EXTRACT(MONTH FROM col)` not `MONTH(col)`
* Use `::text ILIKE '%value%'` for case-insensitive string search
* Use `STRING_AGG(col, ', ')` not `GROUP_CONCAT(col)`
* Use `NOW()` or `CURRENT_TIMESTAMP` not `NOW()` with MySQL-specific modifiers

***

## PDF Export Rules (Dompdf)

All PDF-exported views must follow these constraints:

* **No flexbox or CSS Grid** — use HTML `<table>` layout only
* Font must be **DejaVu Sans** (the only Unicode font bundled with Dompdf)
* Currency symbol must be written as `Rs.` (not the ₹ Unicode symbol, which Dompdf cannot render)
* Images must use absolute server paths or base64-encoded data URIs

***

## Modal Rules

Modals must **never** use `class="hidden"` in the HTML source. Always use CSS `display:none` as the default hidden state. This prevents flash-of-content on page load.

***

## SMTP Configuration

Mail settings are stored in the `crm_mail_configs` database table, **not** in `.env`. This ensures per-tenant mail configuration and persistence across deployments.

***

## Multi-Tenant Data Isolation

Every database query **must** be scoped by `user_id` (the tenant identifier). No cross-tenant data leakage is permitted. The `user_id` is always `Auth::id()` in tenant context.

***

## Post-Deploy Checklist

After every deployment, run these commands in order:

```bash
php artisan view:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
systemctl restart php8.3-fpm
```

The PHP-FPM restart is critical — OPcache must be cleared whenever middleware or service provider files change.

***

## Xena AI Tool Count

| Date       | Total Tools                        |
| ---------- | ---------------------------------- |
| 2026-07-08 | **166 tools** (across all modules) |

Tools are defined in `XenaController::getTools()` and dispatched via `XenaActionService`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xenoraa.com/xenoraa-changelog-and-architecture/key-coding-patterns-and-rules-14.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.