System architecture in detail

The architecture in one sentence

dbxapp is a server-first, state-aware application platform. A single front controller selects a route, establishes the request context, runs a module, renders templates, resolves nested module calls, and returns the final HTML response.

Request pipeline

1. Bootstrap: Composer, the kernel, configuration, and the central API become available.
2. Session: The application loads the current user and persistent UI state.
3. Request normalization: Route, permalink, language, Ajax mode, design, and module parameters are validated.
4. Canonical routing: Invalid aliases redirect to one stable public URL; missing content produces a real 404 response.
5. Module execution: The selected module checks permissions and delegates to its service or view.
6. Presentation: The module result is placed into the active design.
7. Composition: The interpreter resolves nested module calls, while dbxTPL resolves runtime placeholders.
8. Finalization: Protected code examples are restored, the output filter runs, cache rules are applied, and the response is sent.

?dbx_modul=dbxAdmin&dbx_run1=session&dbx_run2=list_session

request → context → permission → module → template → interpreter → response

Public permalinks hide these internal parameters. Direct module routes remain useful for administration, embedded views, tests, and diagnostics.

State and context

The central dbx() API provides validated access to request values and runtime services. New code should use these explicit APIs instead of adding global helper functions.

$db = dbx()->get_system_obj('dbxDB');
$id = dbx()->req('id', 0, 'int');
$design = dbx()->get_system_var('dbx_design', 'dbxapp');

Module-instance isolation matters whenever the same module appears more than once on a page. IDs, form state, report filters, and Ajax targets must never leak between instances.

Templates, interpreter, and inert documentation code

PHP decides what happens; templates define the markup. dbxTPL intentionally offers a small declarative vocabulary:

• {variable} inserts a prepared value.
• [inc=condition]...[/inc] conditionally includes a block.
• [tpl=module|file] includes another template.
• [modul=dbxMenu]...[/modul] composes a module output on the server.

This boundary is security- and documentation-critical: an example must never execute merely because it is displayed on a documentation page.

Data Dictionaries, forms, and reports

A DD is the shared contract for a table: fields, types, indexes, defaults, permissions, ownership, and validation. Product and module code must access data exclusively through dbxDB and a complete DD. Schema changes go through DD synchronization.

dbxForm builds on that contract for input, validation, messages, saving, and callbacks. dbxReport adds filters, sorting, pagination, row actions, and multi-selection while reusing the validated form field model.

$form->set_data_source('myContacts|contact', 'myContacts|contact-form');
$form->load_fd_messages();
$form->save_post('myContacts|contact', $rid);

$report->set_data_definition('myContacts|contact');
$report->set_pagination(true, 20);

The result is a consistent path from database schema to validation and user interface without a second, conflicting metadata layer.

Update-safe extensions with myX

General fixes belong in the dbxapp source and are shipped through the product release. Installation-specific behavior belongs in dbx/modules/myX. Product updates replace product files, but preserve the local myX boundary.

dbx/modules/myX/
├── include/        local services
├── sysclass/       deliberate system-class overrides
├── tpl/htm/        installation-specific templates
└── design/         local presentation additions

This separation keeps upgrades reproducible, makes customer code easy to identify, reduces merge conflicts, and allows local behavior to be tested independently after every update. See the dedicated myX guide for a worked example and acceptance checklist.

Strengths and trade-offs

For data-driven business applications, dbxapp’s combination of DD, forms, reports, permissions, templates, and workflows minimizes repeated infrastructure work. The architecture remains predictable when each layer keeps its documented responsibility.