# Client Portal Engine v2

## Stack

- PHP 8.x multi-page app (each page is a PHP folder under `pages/`)
- Vue 3 (ESM) + Composition API (`.vue` SFC loaded at runtime)
- Bootstrap 5.3.x (CDN)
- No Node.js / no build step (uses importmap + vue3-sfc-loader)

## Folder Structure

- `index.php`: front controller that routes `/{page}` to `pages/{page}/index.php`
- `.htaccess`: hides `.php` and routes pretty URLs to `index.php`
- `app/`: server-side engine (bootstrap, config, helpers, services)
- `src/`: global JS engine + global CSS + shared layout SFCs
- `pages/`: page modules (each page is a folder)

## Page Module Contract

Each page is a folder:

- `pages/{page}/index.php`
- `pages/{page}/page.config.json` (UI version → API version mapping, optionally UI version → variant folder mapping)
- `pages/{page}/common/` (shared components + optional `page.css`)
- `pages/{page}/{variant-or-ui_version}/main-page.vue` (entry SFC)
- `pages/{page}/{variant-or-ui_version}/version.css` (optional)

## Version Resolution

- `?v=latest` or no `?v=` uses `app/app.pages.config.json` (`release` section)
- `?v=1.0` selects a specific UI version from `page.config.json`
- `page.config.json` can map a UI version to a developer-named variant folder (`variant`) for loading `main-page.vue` and `version.css`

## Adding A New Page (Fixed Steps)

1. Create `pages/{new-page}/index.php` and call `app_render_page_shell($bootstrapData)`
2. Create `pages/{new-page}/page.config.json` and add UI/API mappings
3. Create `pages/{new-page}/common/` for shared page components/styles (optional)
4. Create `pages/{new-page}/{ui_version}/main-page.vue` for each UI version
5. Update `app/app.pages.config.json` (`release` section) to set the default UI/API version for the page

## Cookies / Session Notes

- `cp_session`: determines authenticated session (server-side check)
- `cp_api_token`: used by PHP (and exposed to client bootstrap for fetch-based APIs)
