# Project Memory

This file captures stable project context for future Codex sessions working in `/usr/local/var/www/megatron`.

## Stack

- Custom PHP application.
- Routing is handled in [`php/src/bootstrap.php`](/usr/local/var/www/megatron/php/src/bootstrap.php).
- Core infrastructure lives in:
  - [`php/src/Core/Config.php`](/usr/local/var/www/megatron/php/src/Core/Config.php)
  - [`php/src/Core/Database.php`](/usr/local/var/www/megatron/php/src/Core/Database.php)
  - [`php/src/Core/Router.php`](/usr/local/var/www/megatron/php/src/Core/Router.php)
  - [`php/src/Core/View.php`](/usr/local/var/www/megatron/php/src/Core/View.php)
- Database is PostgreSQL via PDO.

## Working Rules

- Follow [`AGENTS.md`](/usr/local/var/www/megatron/AGENTS.md).
- Do not add extra behavior or convenience changes unless explicitly requested.
- For rendering/layout bugs: audit code first, reproduce locally, and separate `Confirmed` from `Hypothesis`.
- For Python/PDF inspection, use:
  - `/Users/kinsleypetit-homme/python-venvs/pymupdf-audit/bin/python`

## Major App Areas

- Clients UI:
  - [`php/views/clients/new.php`](/usr/local/var/www/megatron/php/views/clients/new.php)
  - [`php/views/clients/show.php`](/usr/local/var/www/megatron/php/views/clients/show.php)
- Main repository/data layer:
  - [`php/src/Repositories/ClientRepository.php`](/usr/local/var/www/megatron/php/src/Repositories/ClientRepository.php)
- Shared browser-side helpers:
  - [`php/public/js/app.js`](/usr/local/var/www/megatron/php/public/js/app.js)

## Template Editor Architecture

Confirmed from [`php/docs/template-editor-architecture.md`](/usr/local/var/www/megatron/php/docs/template-editor-architecture.md):

- Separate entry views exist for:
  - [`php/views/tools/paystub_templates.php`](/usr/local/var/www/megatron/php/views/tools/paystub_templates.php)
  - [`php/views/tools/t4_templates.php`](/usr/local/var/www/megatron/php/views/tools/t4_templates.php)
  - [`php/views/tools/statement_templates.php`](/usr/local/var/www/megatron/php/views/tools/statement_templates.php)
- Shared implementation is in:
  - [`php/views/tools/template_editor_core.php`](/usr/local/var/www/megatron/php/views/tools/template_editor_core.php)
- Route families:
  - `/tools/paystub-templates/*`
  - `/tools/t4-templates/*`
  - `/tools/statement-templates/*`
- Renderer split:
  - Paystub: `App\Services\PaystubPdfRenderer`
  - T4: `App\Services\T4PdfRenderer`
  - Statement: `App\Services\StatementTemplatePdfRenderer`

## Storage Conventions

Confirmed from code and docs:

- Paystub template uploads are stored under:
  - `php/runtime/uploads/paystub_templates/`
- Statement guide uploads are stored under:
  - `php/runtime/uploads/statement_guides/`
- Statement template image/assets are stored under:
  - `php/runtime/uploads/statement_template_assets/`
- Layout JSON locations:
  - Paystub layouts: `php/resources/pdf_layouts/paystub/`
  - T4 layouts: `php/resources/pdf_layouts/t4/`
- Active statement-template flow uses:
  - `public.bank_statement_templates`
  - `public.bank_statement_template_guides`
- Legacy statement table still exists:
  - `public.statement_templates`

## Important Past Decision

Recovered from prior local session history:

- Absolute filesystem paths in paystub template storage caused breakage after the project was moved to a new root.
- The direction taken afterward was to normalize stored template paths to relative project paths instead of absolute machine-specific paths.
- When working on file-backed features, prefer project-relative persisted paths unless there is a strong reason not to.

## Statement Template Precision Contract

Confirmed from [`php/docs/statement-template-precision.md`](/usr/local/var/www/megatron/php/docs/statement-template-precision.md):

- Statement editor preview is authoritative at the page-image level.
- Preview background is rendered from the real PDFlib statement test-render output.
- Editor geometry precision target is `0.01 pt`.
- Statement text fields use automatic renderer-side baseline calibration by default.
- `baseline_offset_pt` remains available as a manual override.

## Data Model Notes

Confirmed in [`php/src/Repositories/ClientRepository.php`](/usr/local/var/www/megatron/php/src/Repositories/ClientRepository.php):

- `public.client_id_info` stores client ID-document related fields.
- `public.id_types` exists for ID type lookup.
- `public.clients` has `desj_number`.
- There is extensive app-managed schema setup inside `ClientRepository::ensureEmployeeTables()`.

## Current Gaps To Remember

- The app appears to be primarily app-managed and monolithic; many schema migrations happen in PHP startup logic rather than a separate migration framework.
- There is no confirmed full auth/user model in the inspected code path, so access-control assumptions should not be invented when designing client-facing file features.

## Useful Project Docs

- [`AGENTS.md`](/usr/local/var/www/megatron/AGENTS.md)
- [`php/docs/template-editor-architecture.md`](/usr/local/var/www/megatron/php/docs/template-editor-architecture.md)
- [`php/docs/statement-template-precision.md`](/usr/local/var/www/megatron/php/docs/statement-template-precision.md)

## Session Archaeology Notes

- Local Codex session logs under `$CODEX_HOME/sessions` do contain prior `megatron` work and can be mined when needed.
- Those logs are useful for recovery, but this file should be treated as the preferred durable memory source going forward.