wms-app/docs/reviewing/runtime-architecture.md

Runtime Architecture

This spec covers runtime files that are not owned by a single business module.

Entry Points

File	Role
index.php	Root redirect to landing/ using $base_url from app/config.php.
app/index.php	Authenticated app landing/router entry after login.
app/session.php	Session bootstrap and session guard helpers.
app/dbconn.php	Database connection setup for auth and business databases.
app/preset.php	Shared app initialization values used by pages.
app/include_header.php	Shared HTML head, CSS/JS includes, and page shell dependencies.
app/include_topbar.php	Topbar, branch/company switcher, usage warning badge, and session-visible user context.
app/include_sidebar.php	WMS navigation.
app/include_sidebar_ac.php	Accounting navigation.
app/include_master_sidebar.php	Master-data navigation.
app/include_setting_sidebar.php	Settings navigation.
app/include_ending.php	Shared closing scripts and Socket.IO initialization.

Configuration

app/config.php defines database credentials, base URLs, encryption settings, package tiers, and runtime secrets. app/config.example.php is the template for new environments.

Important runtime values:

• $base_url - public app base URL used for redirects and links.
• $server_url - app URL prefix used by PHP pages for AJAX routes.
• $db_database - auth/identity database.
• $db_database2 - business data database.
• $packages - package tier limits used by UsageGuard.
• Node emit/cron secrets - shared with the Node.js runtime through environment variables.

Database Connections

The app uses two MySQL databases:

Database	Purpose
Auth database	Users, companies, company-user mapping, package usage, SMTP, company settings, schema migration records.
Business database	Products, warehouses, contacts, stock, sales/purchase/finance documents, GL, reports, barcode labels, operation locks.

Most authenticated endpoints load app/assets/utils/db_auth.php, which establishes session context, validates company access, validates CSRF for writes, and exposes $pdo1, $pdo2, $company_id, $user_id, and $user_role.

Node.js Realtime Server

File: nodejs/server.js

The Node.js process hosts the Socket.IO server and a protected HTTP /emit endpoint.

Flow:

1. PHP calls /emit after a successful database commit.
2. The request must include the x-emit-secret header matching EMIT_SECRET.
3. Body contains { event, data, company_id }.
4. Node broadcasts to room company_{company_id}.
5. Browser tabs join their company room through the Socket.IO client initialized in app/include_ending.php.

Environment variables:

Variable	Purpose
PORT	Node HTTP/Socket.IO port; defaults to 3000.
EMIT_SECRET	Shared secret for PHP-to-Node event emission and cron calls.

Node.js Cron Scheduler

File: nodejs/scheduler.js

The scheduler runs alongside the realtime server process and calls PHP cron endpoints over HTTP. It authenticates with the x-cron-secret header using EMIT_SECRET.

Environment variables:

Variable	Purpose
PHP_BASE_URL	Base URL for the PHP host; defaults to http://127.0.0.1.
PHP_WEBROOT	PHP app path; defaults to /mn3wms/app.
EMIT_SECRET	Shared cron secret.

Schedules:

Schedule	Endpoint	Purpose
0 * * * *	/cron/etl_gl_maintenance.php	Repair GL summary gaps for companies in the current hourly slot.
30 * * * *	/cron/etl_stock_maintenance.php	Repair stock summary gaps for companies in the current hourly slot.

Both jobs use company_id % 24 slotting so each company is checked at most once per hour and work is spread across the day.

Setup Script

File: setup.php

setup.php is a CLI-only production bootstrap script. HTTP requests receive 403 and the script exits.

Behavior:

1. Loads database credentials from app/config.php.
2. Connects to MySQL without selecting a database.
3. Creates the auth and business databases if they do not exist.
4. Creates core tables with CREATE TABLE IF NOT EXISTS.
5. Prints a terminal status report.

Dynamic stock tables named td_stock_<warehouse_id> are not created by setup.php; the app creates them when a warehouse is used.

Migration State

The auth database includes a schema_migrations table, but this repository snapshot does not contain a migrations/ directory. Schema setup is currently embedded in setup.php and runtime manager code.