# HIVE ERP foundation — project conventions

## Entry paths

| URL | View | Controller | Guard |
|---|---|---|---|
| `/` / `/login` | `auth/tenant_login.php` | Auth/TenantLoginController | Public, no login yet |
| `/platformhive` | `auth/platform_login.php` | Auth/PlatformLoginController | Public, separate staff login UI |
| `/public` | `public_site/home.php` | PublicSite/HomeController | Public |
| `/app/dashboard` | `tenant/dashboard.php` | Tenant/DashboardController | `tenant-auth` (fail closed) |
| `/platformhive/dashboard` | `platform/dashboard.php` | Platform/DashboardController | `platform-auth` (fail closed) |
| `/app/example` | `Modules/Example/Views/index.php` | ExampleController | `tenant-auth` parent group (fail closed) |

Development-only shell previews: `/_dev/tenant-shell`, `/_dev/platform-shell`, `/_dev/example-module`. They render **no authenticated user/data** and are registered only under `CI_ENVIRONMENT=development`. **Do not deploy development mode.**

## Presentation convention

* `app/Views/layouts/` — tenant, platform, public, auth, pos, print.
* `app/Views/partials/` — shared header, sidebar, footer, head metadata, global modal outlet.
* `app/Views/components/` — reusable HTML fragments (form fields, headings, stats, etc.).
* `modules/<Name>/Views/` — module page content ONLY; extend `layouts/tenant`.
* `public/assets/css/app.css` and `ui-refinements.css` — preserved Step 06 visual baseline.
* `public/assets/css/components/hive-ui.css` — reusable tokens, buttons, form fields, cards, states and page headings.
* `public/assets/css/hive-shell.css` — CI4 shell-specific styles and responsive behavior.
* `public/assets/js/core/hive-shell.js` — client-side shell interactions (mobile nav, local theme).
* `resources/standard-template/hive-ui-step-06-v1.6.1/` — the COMPLETE original prototype (not web-exposed).

**Never** include original `standalone.js` in production layouts; it contains demonstration business state / permissions and would conflict with real server-rendered pages.

## App architecture

`Config/Hive/ModuleRoutes.php` — explicit route-file allowlist. `Config/Hive/Navigation.php` — UI definitions only; no authorization decisions. `Core/Navigation/NavigationBuilder.php` — renders a menu based on registered definitions, to be extended with real permission and module entitlement filtering.

Module namespace `Modules\\Name\\...` resolves to `modules/Name/...`, configured in both Composer PSR-4 and CI4 Autoload config. The sample `modules/Example/` is the **only** sample module. Create additional business modules yourself.

## SECURITY BLOCKERS (intentional, must implement later)

* Login routes POST return HTTP 503 and never create sessions.
* `TenantAuthFilter` and `PlatformAuthFilter` always redirect to their login route. They must be integrated with Shield and policies before enabling private pages.
* No tenant membership, module permission, licensing, access scopes, persistence, billing or real transactions exist yet.
* No mocked user can bypass authentication; development previews are just HTML, unavailable in production mode.
* Implement role, tenant/company and branch policy checks on **every** protected backend route, not just in sidebar visibility. Deny by default.
* Enforce secure HTTPS + correct session/cookie settings in production, and configure CSP & logging as appropriate. All POST routes have CSRF filtering.

## Extending the project

1. Duplicate `modules/Example` and rename namespace, files, views.
2. Add `modules/<New>/Config/Routes.php` to the allowlist in `app/Config/Hive/ModuleRoutes.php`.
3. Register links in `app/Config/Hive/Navigation.php` ONLY after checking authorization at runtime.
4. Extend `layouts/tenant`; reuse UI components and `hive-shell.css` tokens.
5. Connect real services, transactions, migrations, tests and auditing before enabling production use.