# Knowledge Base

Use the smallest document that answers the task. So do not open all files at once, just read the ones you really need it. If you have doubts, ask to the user.

For any database, table, relationship, schema, or migration task, read [04-database-relationships.md](04-database-relationships.md) before inspecting SQL files. Treat it as the canonical relationship map.

## Architecture

| Topic | Use when | File |
|---|---|---|
| Code conventions | Matching local style and file layout | [01-code-conventions.md](01-code-conventions.md) |
| Architecture | Following request flow or locating page logic, also create, modify or update pages (views, controllers, js) but no for only models | [02-architecture.md](02-architecture.md) |
| Models Convention | To create or modify files at `src/model/` or source-specific behavior, also if you need to check api that it's not found on the docs | [03-models-convention.md](03-models-convention.md) |
| Database relationships | Any table lookup, join, schema change, migration, or database-backed feature | [04-database-relationships.md](04-database-relationships.md) |
| Content management | CMS content nodes, translations, publication, admin tree, editor recovery, or content schema | [05-content-management.md](05-content-management.md) |
| Testing | Running, adding, modifying tests or adding coverage | [09-testing-guide.md](09-testing-guide.md) |
| Cart and orders | Modifying carts, order payment, or claim status | [20-cart-orders.md](20-cart-orders.md) |
| Admin orders management | GM order search, order details, or internal payment approval | [../api/pages/admin__orders-management.md](../api/pages/admin__orders-management.md) |
| Payment discounts and cart payment flow | Any payment configuration, pricing, provider callback, manual payment, purchase-history payment, or pending-cart change. It documents the current pricing contract, callback ownership, manual-payment path, pending-order rendering, and AJAX query boundary. | [21-payment-discounts.md](21-payment-discounts.md) |
| PayPal v2 payment adapter | PayPal v2 SDK, wallet funding sources, webhook, retry, idempotency, and CLI reconciliation | [../api/modules/payment/paypalv2.module.md](../api/modules/payment/paypalv2.module.md) |
| Emails | Only when the prompt requires creating or modifying application emails | [11-emails.md](11-emails.md) |
| Authentication rate limits | Login blocking, account lockouts, registration throttling, or limiter schema | [12-rate-limits.md](12-rate-limits.md) |
| Authentication and MFA | Login state, MFA enrollment/challenge flow, security sessions, or protected routes | [13-authentication-security.md](13-authentication-security.md) |


## API

| Topic | Use when | File |
|---|---|---|
| CLI tool and commands | Adding or changing CLI controllers, commands, importers, or CLI argument handling | [CLI API](../api/cli.md) |
| Models API | All available models and methods to access the data | [models.md](../api/models.md) |
| Form Components API | Form component methods and overrides | [form-components.md](../api/form-components.md) |
| Template Components API | Page, block, and field helpers | [template-components.md](../api/template-components.md) |
| Component Playground | Shared component showcase and update workflow | [playground.md](../api/playground.md) |


## Quick commands

- Format touched PHP files: `make pretty`
- Run main model suite: `composer test`
- Run web suite: `composer run test-web`
- Run payment module tests: `composer run test-web-modules`
- Run CMS model tests: `composer run test-model-cms`