# NexusCRM Codebase

## Directory Structure
The project follows a standard Clean Architecture layout with a specialized `scripts/` hierarchy.

### `/scripts` (Operational Tooling)
*   `verify_codegen.sh`: **Primary CI gate**. Verifies generated files are in sync with source definitions and enforces no hardcoded table/field names in frontend code.
*   `constraint_check.py`: Architecture guard — ensures no business objects leak into `system_tables.json`.

### `/.githooks` (Git Hooks)
*   `pre-commit`: Runs `verify_codegen.sh` + `constraint_check.py` before every commit. Activate with: `git config core.hooksPath .githooks`

## Architectural Standards

### Persistence & Aliasing
**Strict Logical-to-Physical Parity** is enforced to decouple the API Layer from the Database Layer.

1.  **Logical Layer (API/Service)**: Always use Logical Field Names (e.g., `Id`, `CreatedDate`, `CustomField__c`).
2.  **Query Builder**: The `pkg/query` Builder is the **only** authorized way to construct standard queries. It automatically resolves Logical Names to Physical Names.
3.  **Physical Layer (DB)**: Raw SQL is **prohibited** except in specific "Authorized Exceptions" (e.g., Bulk Loading, Schema DDL). In these cases, you MUST explicitly use Physical Column Names (e.g., `constants.ColID`).

**Critical Rule**: Always rely on standard logical references when interacting with the Query Builder.

### Constants
*   `constants.Field*` = Logical Name (e.g., "Id") -> **Use in Builder**
*   `constants.Col*` = Physical Name (e.g., "Id") -> **Use in Raw SQL/DDL**

## Verification
Run `python3 scripts/verify/checklist.py` to validate the environment.