toga-ai 1.0.0

package/knowledge/1.0/standards/backend-php.md

@@ -0,0 +1,450 @@
+---
+title: Back-End Coding Standards
+framework: "1.0"
+project: Library
+client: shared
+type: standard
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/library/architecture.md
+  - ../../2.0/standards/backend-php.md
+---
+
+# Back-End Coding Standards (1.0 Legacy — `App_` Framework)
+
+> **Scope & posture.** These standards cover server-side PHP for the legacy **1.0**
+> framework — the `App_`/`Browser_` codebase built on the **`library`** repo (the 2.0
+> framework is `_underscore`; see its own backend standard). 1.0 is a mature, maintenance-mode
+> codebase with **far less consistency** than 2.0. This document **describes how the legacy
+> code actually works** so that new and modified code stays consistent with the surrounding
+> code. Where a convention is strong and universal, follow it strictly; where the codebase is
+> historically inconsistent, this is called out — match the local file you're editing and
+> prefer the cleaner pattern for new code. **Do not** retrofit 2.0 conventions (UUIDs,
+> `utf8mb4`, metadata-driven APIs) onto 1.0.
+
+## General Principals
+
+### Modularity and Reusability
+
+* Ensure that the code is modular, making use of functions and classes to promote reusability and separation of concerns.
+
+## Framework & Project Structure
+
+### The `library` repo
+
+* `library` is the shared code for **all 1.0 applications** — the `App_` framework. Target PHP 7.2+, compatible through 8.1.
+* **`library/app/`** — back-end logic, class prefix `App_` (no HTML output).
+* **`library/browser/`** — server-rendered UI, class prefix `Browser_` (emits HTML).
+* **`resources/` repo** — purely front-end assets (JS/CSS). **Do not put front-end assets in `library`.**
+* Consuming apps use **no Composer** — `library` *is* the vendor directory. Add third-party packages directly to `library` as top-level folders.
+
+### Bootstrap & autoloader (`_.php`)
+
+* Every app starts with `require_once '/path/to/library/_.php';`. It sets the PHP environment (`display_errors`, `error_reporting(E_ALL)`, timezone **`America/Chicago`**), defines `__APPROOT__` (the ancestor folder containing a `_` directory) and `__LIBROOT__` (the `library/` dir), and registers the autoloader.
+* **Class-to-file mapping:** replace every `_` with `/`, **lowercase the entire result**, append `.php`. Both `__APPROOT__` and `__LIBROOT__` are searched, so app classes can **shadow** library classes.
+
+```
+App_Model_Client                  → app/model/client.php
+Browser_Form_Input_Autocomplete   → browser/form/input/autocomplete.php
+```
+
+* All folder/file names **must be lowercase**. Class names are not case-sensitive (the autoloader lowercases before lookup). Namespace separators (`\`) normalize to `_`.
+
+### Conventions you must know
+
+* **`debugVar($input, $stopExecution, $withHrLineBreaker)`** is the global debug dump helper. **Remove all `debugVar()` calls before merging.**
+* **`DOA_` prefix** (on files, folders, classes, and methods) marks **deprecated/legacy code that is still in active use** ("Dead On Arrival"). Do not build new functionality on `DOA_`-prefixed code; do not assume it is safe to delete — it often still has live dependencies. Check for an explicit removal note before touching it.
+
+## Database/SQL
+
+> **Legacy DB reality (verified against production):** legacy schemas (`Core`, `TOGA_<client>`,
+> `Vision`, …) are **`InnoDB`** but use the **`latin1_swedish_ci`** collation throughout — not
+> `utf8mb4`. Tables have an **`id`** auto-increment primary key and **no `uuid` column**, **no
+> `c_` custom-field prefix**, and **almost no column/table comments**. This is the opposite of
+> 2.0 on those points — do not import the 2.0 rules. The naming conventions, however, are
+> shared (PascalCase tables, camelCase fields).
+
+### Table Design — Order of Fields
+
+1. `id` (mandatory — auto-increment unsigned primary key)
+2. Foreign Keys
+3. Record Identifiers (references like order number)
+4. Date/Time fields (legacy uses a `dt` prefix, e.g. `dtCreated`, `dtUpdated`)
+5. Date fields
+6. Flag/Boolean fields (`is`-prefixed)
+7. ENUM-type fields (lists)
+8. Char/Varchar/Integer/Decimal fields
+9. Text/Blob fields
+
+> Note vs 2.0: legacy has **no `uuid` second column** and **no trailing `c_` custom-field
+> block**. The primary key alone (`id`) identifies a record.
+
+### Primary Keys & IDs
+
+* Every table has an `id` column: `INT UNSIGNED`, `AUTO_INCREMENT`, primary key, as the **first** column.
+* There is no external/UUID identifier in legacy. Do not add a `uuid` column to a legacy table unless a feature explicitly requires it.
+
+### Engine, Character Set & Collation
+
+* All tables use the **`InnoDB`** engine.
+* Legacy tables use **`latin1_swedish_ci`**. New tables in a legacy database should **match the collation of the database/tables they join against** — mixing `latin1` and `utf8mb4` columns in a `JOIN`/`WHERE` causes "Illegal mix of collations" errors. Do not introduce `utf8mb4_0900_ai_ci` (the 2.0 standard) into a legacy schema without confirming every joined column is migrated.
+
+### Table & Field Comments
+
+* Legacy tables and columns are almost never commented. Comments are **encouraged for new columns** but are not historically enforced here. Where you do comment, keep it short and descriptive and do not begin with "The".
+
+### Queries
+
+* `SELECT *` is fine in your MySQL client but should be avoided in code (it stresses the server and breaks when columns change). Note the framework utility `App_Database::lookupRecord()` uses `SELECT *` internally by design — that is acceptable for that generic helper, not a license to use it in feature code.
+
+#### Capitalization
+
+* Capitalize all SQL keywords (`SELECT`, `FROM`, `INNER JOIN`, `ON`, `WHERE`, `AND`, `OR`, `LIKE`, `AS`, `ORDER BY`, `DESC`, `LIMIT`, `GROUP BY`, `HAVING`, etc.).
+
+```sql
+# Bad
+select column1 from table1
+
+# Good
+SELECT column1 FROM table1
+```
+
+#### Spacing & SQL within PHP
+
+> Legacy application code is **inconsistent** about SQL formatting. Framework code mostly
+> follows the rules below; match this style for any new or modified SQL.
+
+1. Use tabs for indentation.
+2. Every clause starts on a new line; indent the column list and conditions.
+3. A line break after each comma in the `SELECT` column list.
+4. `SELECT`, `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY` on their own lines.
+5. When writing SQL in PHP, put the opening/closing quotes on their own lines and indent the query.
+
+```php
+$sql = "
+	SELECT
+		column1,
+		column2
+	FROM TableName
+	WHERE
+		val > 0
+	ORDER BY
+		column1 DESC
+	LIMIT 10
+";
+$res = App_Database::query($sql, 'db_toga');
+```
+
+#### Aliasing, Joining, Subqueries, Conditions
+
+* Alias tables only when necessary (e.g. self-joins or duplicate table names); use `AS` for derived columns.
+* Each `JOIN` on its own line; put `INNER JOIN`s before outer joins; prefer `LEFT OUTER JOIN` over `RIGHT OUTER JOIN`.
+* Enclose subqueries in parentheses, start them on a new line, and indent them.
+* Put multiple `WHERE` conditions on separate lines; start `AND`/`OR` on a new line; **use parentheses whenever mixing `AND` and `OR`**; surround operators (`>`, `<`, `=`) with spaces.
+
+#### SQL Comments
+
+* Prefer `#` over `--` to begin a SQL comment; keep comments concise and place them above the code they describe.
+
+### Encoding
+
+* Data inserted into the database must already be decoded (not HTML- or URL-encoded) unless a column is explicitly intended to store encoded content — store the real `<` character, not `&lt;`.
+
+### SQL Naming Conventions
+
+These conventions are shared with 2.0 and **do hold** across legacy schemas.
+
+* **Case:** database names PascalCase or their formal name (e.g. `TOGA`), table names **PascalCase**, field names **camelCase**.
+* **Foreign keys:** take the referenced table, singularize it, append `Id`, camelCase it — `Clients` → `clientId`, `PurchaseOrders` → `purchaseOrderId`. (Legacy FKs are `INT UNSIGNED`.)
+* **Human-readable field:** call it `name` — not `label`, `type`, `displayName`, or `companyName`.
+* **Bridge tables:** join the two table names with an underscore, parent first, keeping plurals aligned with the real table names (e.g. `Locations_LocationAttributes`).
+
+### SQL Data Types via `App_Model`
+
+In code you rarely write raw column types — an `App_Model` declares each column as a `FIELDTYPE_*` constant that maps to the underlying type. The 1.0 constants (note the `FIELDTYPE_` prefix; 2.0 uses `FIELD_`):
+
+| Constant | Purpose |
+|---|---|
+| `FIELDTYPE_PRIMARYKEY` / `FIELDTYPE_FOREIGNKEY` | unsigned int key columns |
+| `FIELDTYPE_INT` / `FIELDTYPE_INT_AUTONUMBER` | integers |
+| `FIELDTYPE_BOOLEAN` | `is`-flag tinyint |
+| `FIELDTYPE_DECIMAL` | decimals |
+| `FIELDTYPE_CHAR` / `FIELDTYPE_CHAR_CAPS` / `FIELDTYPE_CHAR_UCWORDS` / `FIELDTYPE_CHAR_HTMLENTITY` / `FIELDTYPE_CHAR_PASSWORD` / `FIELDTYPE_PHONE` | string variants |
+| `FIELDTYPE_LIST` | ENUM/list |
+| `FIELDTYPE_DATE` / `FIELDTYPE_DATETIME` / `FIELDTYPE_DATETIME_CREATED` / `FIELDTYPE_DATETIME_UPDATED` / `FIELDTYPE_TIME` / `FIELDTYPE_YEAR` | date/time (CREATED/UPDATED auto-managed) |
+| `FIELDTYPE_BLOB` / `FIELDTYPE_BLOBSTORAGE` | binary / external blob storage |
+| `FIELDTYPE_SERIALIZED` | PHP-serialized payload |
+
+#### Flags/Booleans
+
+* Flag fields begin with `is` (e.g. `isVisible`) and use `FIELDTYPE_BOOLEAN` (`UNSIGNED TINYINT`, `0` = false, `1` = true).
+
+#### Integers
+
+* Primary and foreign keys must be **unsigned** integers. Choose the smallest integer type that fits the range; use unsigned unless negative values are genuinely required.
+
+### SQL Injection Prevention
+
+* Never interpolate raw user input into a query string. In order of preference:
+  1. **Use the `App_Model` layer** — it builds and escapes queries for you.
+  2. **When writing SQL by hand, escape every interpolated value with `App_Database::sqlEscape()`** before placing it in the query string. In `browser/` action files the helper `getVarEscaped('field')` wraps `sqlEscape()` for request values.
+* `App_Database::sqlEscape()` escapes a value for safe interpolation (and handles arrays/objects recursively). `App_Database::sqlProtect()` is a **stricter, lossy filter** that *strips* `% \ / * " '` and the literal ` or` — use it only to sanitize free-form search input, never for values you intend to store intact.
+* Legacy uses **mysqli** (via `App_Database`), not PDO/prepared statements; escaping discipline at the call site is the control.
+
+```php
+// Bad — raw interpolation
+$sql = "SELECT id FROM Users WHERE email = '$email'";
+
+// Good — escape before interpolating
+$email = App_Database::sqlEscape($email);
+$sql = "
+	SELECT
+		id
+	FROM Users
+	WHERE
+		email = '$email'
+";
+
+// Better — let the model layer handle it
+$user = new App_Model_User();
+// ...set lookup fields and load...
+```
+
+## PHP
+
+### PHP Tags
+
+* Short tags (`<?`) are **not** permitted — always `<?php`.
+* PHP files **MUST NOT** end with a closing `?>` tag (prevents accidental output of trailing whitespace).
+
+### File & Class Naming
+
+* Files and folders are **all lowercase**; the path mirrors the class name with `_` → `/` (see autoloader above).
+* Back-end logic classes are prefixed `App_`; server-rendered UI classes are prefixed `Browser_`.
+
+### Code Formatting
+
+#### Indentation
+
+* Use **tabs** for indentation, not spaces. (Universal in this codebase.)
+
+#### Braces
+
+* Opening braces for classes, methods, and control structures go on the **same line**.
+
+```php
+if ($condition) {
+	// code
+} else {
+	// code
+}
+```
+
+### Naming Conventions
+
+* **Variables:** camelCase, descriptive (`$primaryKeyId`, `$fieldChanges`).
+* **Methods/functions:** camelCase (`buildModel()`, `getChangedFields()`).
+* **Constants:** `UPPERCASE_SNAKE_CASE` (`FIELDTYPE_PRIMARYKEY`, `TABLENAME`, `MODE_EDIT`).
+* **Classes:** PascalCase with the `App_`/`Browser_` prefix.
+
+### Positional Arguments (not named)
+
+* 1.0 targets PHP 7.2 and the codebase uses **positional arguments only** — do **not** use PHP 8 named arguments (`substr(string: $x)`) here. (This is the opposite of the 2.0 standard.)
+
+```php
+// Correct for 1.0
+$piece = substr($value, 0, 8);
+```
+
+### Documentation
+
+* **DocBlocks:** framework (`library`) classes/methods are well documented with a description and `@param`/`@return`/`@throws`. Application code is less consistent — document new and modified methods to the framework standard.
+* **Comments:** explain the "why", not the "how"; use inline comments sparingly.
+
+### Performance
+
+* Use single quotes for strings unless interpolation is needed (`'Hello'`, `"Hello $world"`, `'Hello ' . $world`). Note: legacy code is pragmatic and mixed here; prefer the rule for new code.
+
+### Miscellaneous
+
+* Use `require_once` for include-once files. Avoid global variables and global state.
+
+## App_Model layer (the 1.0 ORM)
+
+Each DB table has a model under `app/model/` extending `App_Model`.
+
+```php
+class App_Model_Client extends App_Model {
+	const TABLENAME = 'Clients';
+	const DATABASE  = 'db_toga';
+
+	public $id           = self::FIELDTYPE_PRIMARYKEY;
+	public $clientName   = self::FIELDTYPE_CHAR;
+	public $companyId    = array(self::FIELDTYPE_FOREIGNKEY, 'App_Model_Company'); // FK → parent model
+	public $active       = array(self::FIELDTYPE_BOOLEAN, 1);                       // [type, default]
+}
+```
+
+* Declare the table via `TABLENAME` and the connection via `DATABASE`.
+* Declare each column as a public property set to a `FIELDTYPE_*` constant, **or** an array `[FIELDTYPE_*, default]`; foreign keys may carry the parent model name as a second element.
+* CRUD / instance methods: `save($okayToLog = true, ...)` (insert or update by PK), `delete()`, `buildModel()` (load by PK — the constructor calls it when given an id), `getChangedFields()`.
+* Static helpers: `lookupLabel($id)`, `lookupValue($id, $field)`, `exists($id)`, `fetchCount($conditions)`, `deleteWhere($include, $exclude)`.
+* Models may also define UI-binding constants (`ACTION`, `VIEW`, `LISTING`, `TABS`) tying the model to its `browser/` screens.
+* **Client-specific behavior** lives in `app/client/` overrides — keep tenant logic there, not in the base model.
+
+## App_Database layer
+
+`App_Database` is a static wrapper over **mysqli** with result caching and query helpers. Connections are addressed by a link-registry string (e.g. `'db_toga'`, `'db_catalog'`).
+
+* **Run a query:** `App_Database::query($sql, $linkRegistryString = '')`.
+* **Read results:** `fetchRow(&$res)`, `fetchOne(&$res, $rowIndex, $colIndexOrField)`, `numRows(&$res)`.
+* **Writes:** `affectedRows($link)`, `getInsertId($link)`.
+* **Cached lookups:** `lookupField($table, $aryLookup, $returnField, $link, $throwIfNotFound)`, `lookupRecord($table, $idValue, $link)`.
+* **Escaping:** `sqlEscape()` (safe interpolation) and `sqlProtect()` (strict, lossy filter) — see SQL Injection Prevention.
+
+## browser/ — Server-Rendered UI
+
+The `browser/` tree renders HTML server-side. Components are `Browser_*` classes in lowercase files (`Browser_Datagrid` → `browser/datagrid.php`, `Browser_Form_Input_Text` → `browser/form/input/text.php`).
+
+### Core components
+
+| Component | Purpose |
+|---|---|
+| `Browser_Datagrid` | Table/list view with filtering, sorting, pagination, bulk edit (140+ subclasses in `datagrid/`) |
+| `Browser_Form` + `Browser_Form_Input_*` | Form builder and field elements (Text, Textarea, Select, Checkbox, Datepicker, Autocomplete, Button, …) |
+| `Browser_Dialog` | Modal dialogs |
+| `Browser_ButtonBar` + `Browser_ButtonBar_Button_*` | Button toolbars (Save, Cancel, Edit, Delete, Import, …) |
+| `Browser_Breadcrumb` | Navigation trail |
+| `Browser_Sidebar` | Sidebar modules |
+| `Browser_Widget` | Dashboard widgets |
+| `Browser_Status` | Status badges (40+ subclasses in `status/`) |
+| `Browser_Message` | Alert/message boxes |
+
+### Page pattern — action.php + view.php
+
+A screen is a folder under an app's `app/` tree with paired files:
+
+* **`action.php`** — reads `$_REQUEST`/mode (`MODE_NEW`, `MODE_EDIT`), validates (`Browser_Form_Validator::isValid()`), and writes to the DB, then redirects/sets state.
+* **`view.php`** — instantiates `Browser_*` components and renders them. Optional `tabs.php`, `summary.php`, `listing.php`.
+
+```php
+// view.php (abridged)
+$buttonBar = new Browser_ButtonBar();
+$buttonBar->addButton(new Browser_ButtonBar_Button_Save());
+
+$form = new Browser_Form();
+$form->setAction(linkProductBundle($id, array('mode' => $mode), '..._action'));
+$form->registerButtonBar($buttonBar);
+$form->renderFormHeader();
+$form->groupHeader('Product Bundle Information');
+
+$element = new Browser_Form_Input_Text('name');
+$element->setLabel('Name');
+$element->setRequired(true);
+echo $element->renderField();
+
+$form->groupFooter();
+$form->renderFormFooter();
+```
+
+### Datagrid pattern
+
+Subclass `Browser_Datagrid` and configure it in the constructor — columns are added via `addField()`, not declared as properties:
+
+```php
+class Browser_Datagrid_Accounts extends Browser_Datagrid {
+	public function __construct() {
+		parent::__construct('accounts');
+		$this->setTitle('Accounts');
+		$this->setTableJoins("
+			FROM Companies
+			LEFT OUTER JOIN Users AS AccountManagers ON ...
+		");
+		$this->setViewLink(linkCompany('!Companies.id!'));   // !Field! = row-value placeholder
+		$this->addField('active', 'Active', 'Companies.active', self::FILTERABLE,
+			array('style' => self::STYLE_BOOLEAN));
+	}
+}
+```
+
+* Column display uses `STYLE_*` constants (`STYLE_DATE`, `STYLE_CURRENCY`, `STYLE_BOOLEAN`, `STYLE_STOPLIGHT`, …).
+* Filterability via `self::FILTERABLE` / `self::SEARCHABLE`.
+* `!TableAlias.column!` placeholders are replaced per-row when building links.
+
+### Rendering & output
+
+* Components render by **echoing HTML directly** (`render()` / `renderField()`), mixing PHP and HTML via inline `?> … <?php` fragments and heredocs. There is no separate template engine.
+* For a string instead of direct output, components use `App_Page::startCapture()` / `App_Page::stopCapture()` (output buffering); many `render*` methods accept a `$renderAsString` flag.
+
+### HTML escaping (a known weak spot — do better in new code)
+
+* Input values are escaped with `App_String::htmlEscapeQuotes()` / `htmlentities()` in some elements, **but escaping is inconsistent** across the layer (textarea, dialog, and datagrid-injected JS frequently emit unescaped strings).
+* **For new/modified UI code, escape all output that contains user/DB data** (`App_String::htmlEntity()` / `htmlEscapeQuotes()`), especially anything interpolated into HTML attributes or inline `<script>`.
+
+### browser/ structure
+
+* Lowercase files organized by component type: `datagrid/`, `form/`, `form/input/`, `dialog/`, `status/`, `sidebar/`, `buttonbar/`, `buttonbar/button/`, `widget/`.
+
+## Error Handling
+
+* Throw exceptions for unexpected conditions: `throw new Exception('message')` is the prevailing pattern (an `App_Exception` class exists but is rarely used for throwing — match the surrounding file).
+* Catch and handle exceptions where you can add value; provide meaningful messages.
+* The `@` error-suppression operator is acceptable only for defensive file I/O (e.g. reading an optional cache file); do not use it to hide real errors.
+* Use structured logging to capture application behavior and errors.
+
+## Security Best Practices
+
+### Input Validation and Sanitization
+
+* Validate and sanitize all user input (see SQL Injection Prevention and HTML escaping above).
+
+### Secure Communication
+
+* Always use HTTPS to encrypt data in transit.
+
+### Authentication and Authorization
+
+* Use the framework's `App_Auth` / `App_Acl` for authentication and role-based access control; do not roll your own session/permission checks.
+
+## Performance Optimization
+
+### Caching
+
+* `App_Database` provides built-in result caching for repeated lookups (`lookupField`/`lookupRecord`). Reuse it rather than re-running identical reads. Store per-request reusable data in variables; use sessions/cookies for cross-request client state.
+
+### Asynchronous / Background Processing
+
+* For long-running or background work, hand off to the legacy worker tier (the `worker` / `worker1.5` apps) rather than running long tasks inline in a web request. Use AJAX for front-end interactions.
+
+## API Design
+
+### Outbound / integration APIs (`App_Api`)
+
+* Third-party integrations live under `app/api/` as `abstract class App_Api_<Vendor> extends App_Api`, with static methods and an `initialize()` for setup; results are returned via `App_ApiResult`.
+* RESTful principles apply when *we* expose endpoints, but many legacy partner/3rd-party APIs are not REST — follow the partner's contract.
+
+> Note: the 2.0 metadata-driven API features (Record Scripts, API Payload Interceptors,
+> `/v2` engine) **do not exist in 1.0**. Do not reference them in legacy code.
+
+## Logging and Monitoring
+
+* Use structured logging with relevant context. Field/record change logging is available via the model layer (`App_FieldLog`) — keep `save()` logging enabled unless there's a reason not to.
+* Implement monitoring/alerting to catch issues early (the `systemmonitor/` helpers support this).
+
+## Configuration Management
+
+* Manage configuration through `App_Config` and per-environment config files. Keep secrets out of source where possible.
+
+## Code Quality and Maintainability
+
+* Establish a thorough code review process.
+* **Remove all `debugVar()` calls before merging.**
+* Don't extend `DOA_`-prefixed code; plan its removal when you touch the area and dependencies allow.
+
+## Documentation
+
+* Keep code well-documented with DocBlocks and usage examples.
+* Maintain clear API documentation for endpoints we expose; use Postman for API testing/storage where applicable.

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -0,0 +1,6 @@
+# _underscore (_Underscore) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
+| [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |

package/knowledge/2.0/apps/_underscore/architecture.md

@@ -0,0 +1,183 @@
+---
+title: _underscore Framework Architecture
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: architecture
+status: active
+updated: 2026-06-08
+owners: [jcardinal]
+files:
+  - _underscore/_underscore.php
+  - _underscore/Loader.php
+  - _underscore/Framework.php
+  - _underscore/Model.php
+  - _underscore/Database.php
+  - _underscore/Query.php
+  - _underscore/Route.php
+  - _underscore/Component.php
+related: []
+---
+
+## Summary
+
+`_underscore` is the shared PHP backend framework for **all 2.0 applications**. It
+provides database abstraction, ORM-style models, routing, component rendering,
+configuration, ACL, and third-party integrations. Every 2.0 project depends on it.
+Minimum PHP 8.1 (enforced in `_underscore.php`). The current architecture is
+**decoupled**: React handles the frontend; `_underscore` serves as the backend API layer.
+
+## Entry point & boot sequence
+
+Every 2.0 project's `index.php` is just `<?php require '_underscore.php';`.
+
+1. `_underscore.php` — PHP version check, require `Initialize.php`
+2. `Initialize.php` — sets `_START_TIME`, loads interfaces, `Time.php`, `Loader.php`
+3. `Loader.php::initialize()` — registers the SPL autoloader, then in order:
+   `_Error::initialize()` → `_Environment::initialize()` → `_Config::initialize()`
+   (parses INI) → `_Time::initialize()` → **`_underscore::initialize()`** (project hook,
+   required) → `_Session::initialize()` → `_Route::initialize()` (web only).
+
+## Naming convention & autoloader
+
+Class names map **directly** to file paths: replace each `_` with `/`; the last segment
+is the `.php` filename. **Case-sensitive.**
+
+| Class | File |
+|---|---|
+| `_Model_Client_User` | `Model/Client/User.php` |
+| `_Model_Compass_SalesOrder` | `Model/Compass/SalesOrder.php` |
+| `_Component_Ui_Button` | `Component/Ui/Button.php` |
+
+The autoloader resolves framework root first, then the project namespace. External
+libraries register via `_Framework::registerLibrary()`. There is **no Composer** for
+core PHP deps; frontend libs (Bootstrap 5.1.3, Font Awesome 6) are vendored in
+`Component/Library/`.
+
+## Database architecture
+
+Built for multi-tenant, multi-database apps. Connections register via
+`_Database::register()`; well-known categories:
+
+| Constant | Description |
+|---|---|
+| `_underscore::DB_CORE` | Shared infra DB — clients, domains, environments, ACL, parameters. Models in `Model/Core/`. |
+| `_underscore::DB_CLIENT` | Per-client business data; each client has an isolated DB. Models in `Model/Client/`. |
+| `_underscore::DB_LOGS` | Core-level logging (non-client). |
+| `_underscore::DB_CLIENT_LOGS` | Per-client logging / audit trails. |
+
+`Database.php` handles named connections with read/write replica separation, **lazy
+transactions** (a transaction starts only on first write), result caching, and
+multi-tenant client-DB lookup from Core. `Query.php` wraps MySQLi with read/write
+auto-routing and result helpers: `fetchRows()`, `fetchRow()`, `fetchOne()`,
+`fetchRowsAssocArray()`, `fetchKeyValuePairs()`, `fetchValues()`.
+
+## Model layer
+
+Each DB table has a model. Every model must define:
+
+```php
+const DATABASE = _underscore::DB_CLIENT;  // or DB_CORE
+const TABLE    = 'TableName';
+```
+
+Columns are declared as `public` properties set to field-type constants. Numeric
+(`FIELD_PRIMARYKEY`, `FIELD_FOREIGNKEY`, `FIELD_INTEGER`, `FIELD_BOOLEAN`,
+`FIELD_DECIMAL`…), string (`FIELD_CHAR`, `FIELD_CHAR_CAPS`, `FIELD_CHAR_UUID`,
+`FIELD_LIST`…), date/time (`FIELD_DATE`, `FIELD_DATETIME`, `FIELD_DATETIME_CREATED`
+auto-set on insert, `FIELD_DATETIME_UPDATED` auto-set on save), binary
+(`FIELD_BLOB`, `FIELD_STORAGE` for S3/filesystem), and calculated (`FIELD_SQL`).
+
+**Foreign keys** are arrays with the target model:
+
+```php
+public $salesOrderId = [
+    self::FIELD_FOREIGNKEY,
+    self::FIELDOPT_FOREIGNKEY_MODEL => '\_Model_Client_SalesOrder'
+];
+```
+
+### Calculated (SQL) fields
+
+`FIELD_SQL` declares a computed field (always prefixed `_`). A static method of the
+same name returns a raw SQL expression used inline in queries:
+
+```php
+public $_extPrice = [self::FIELD_SQL, self::FIELDOPT_SQL_TYPE => self::FIELD_DECIMAL];
+public static function _extPrice($table = self::TABLE) {
+    return "($table.quantity * $table.price)";
+}
+```
+
+`FIELDOPT_SQL_STORED => true` persists the result to a real column on save (must be
+refreshed after bulk migrations); default `false` recalculates on every query.
+
+### CRUD
+
+```php
+$po = new _Model_Team_PullRequest();      // create
+$po->title = $title; $po->save();
+
+$po = new _Model_Team_PullRequest(123);    // update by PK
+$po->title = $new; $po->save();
+
+$v = new _Model_Client_TableView();        // load single
+$v->slug = $slug; $v->isActive = true;
+if ($v->load()) { /* found */ }
+
+$s = new _Model_Client_State();            // search many
+$s->name = $name; $states = $s->search();
+```
+
+### Client-specific model extensions
+
+`Model/Client/` holds base models for all clients. A client needing custom logic gets a
+directory (`Model/Compass/`, `Model/Aig/`, `Model/Canon/`) with classes extending the
+base — e.g. `_Model_Compass_SalesOrder extends _Model_Client_SalesOrder`. Supports
+deeply nested sub-clients (`Model/Compass/Canada/`). **This is the multi-tenant
+customization hook — client behavior lives here, not in the API engine.**
+
+## Interceptors
+
+Static methods on a model that intercept API calls before/after the HTTP method:
+`[pre|post][HttpMethod](&$api, &$payload)` — e.g. `postPost`, `prePut`, `preDelete`.
+Both args by reference; interceptors **do not return** — they mutate `$payload` and/or
+perform side effects. `$api` carries user identity, JWT, client info, headers, route.
+
+## Scripted APIs & internal requests
+
+A **Scripted API** is a custom static method acting as a full endpoint; first arg is
+`&$api`, subsequent args come from the query string, and it **must return** a value
+(JSON-encoded as the response). `$api->internalApiRequest($method, $route, $payload,
+$options)` invokes another endpoint in-process (no HTTP round trip), reusing auth/ACL —
+heavily used by interceptors and NetSuite traits.
+
+## Traits
+
+`Trait/` composes shared model functionality: `Trait/Netsuite/` (22 ERP-sync traits:
+SalesOrder, Invoice, Item, Customer, …), `Trait/Startech/`, `Trait/Ai/Bdr/`,
+`Trait/NonStatic/` (`PrePost`, `Href`, `Toggle`, `ViewDataGetSet`), `Trait/Static/`.
+
+## Routing & components
+
+`Route.php` parses the URI to a controller method via reflection: URI segments
+(kebab-case → camelCase) become candidate method names; parameter names use the `inp`
+prefix by default (`sales-orders` → `$inpSalesOrders`). `Component.php` renders
+multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentName>` tags.
+
+## Configuration
+
+`Config/[environment].ini`, accessed via `_Config::database('username')`,
+`_Config::debug('show_queries')`. Groups: `[_underscore]`, `[database]`, `[debug]`,
+`[api]` (per-hostname).
+
+## Key abstractions
+
+| Class | Purpose |
+|---|---|
+| `_Framework` | Abstract base all projects extend; `initialize()`, `pre()`, `post()`, DB/folder constants |
+| `_Model` / `_Model_True` | Base ORM (field types, CRUD, FK traversal, SQL fields) |
+| `_Database` / `_Query` | Connection pool + read/write routing / MySQLi wrapper with caching |
+| `_Route` / `_Component` | URI router / HTML component renderer |
+| `_Config` / `_Environment` / `_Loader` / `_Http` / `_Error` | config, env/debug, autoload, JWT/HTTP, errors |