Codex Guide

1. Contract

Codex will evolve dbxapp into a Borland, Concept16 and DataFlex-inspired PHP web RAD runtime. The goal is a clear, fast, secure and predictable runtime for business applications.

The development follows the LEGO principle:

Wenige genormte Anschluesse.
Viele kombinierbare Bausteine.
Keine versteckte Magie im Kern.
Wow-Effekt im UI.
Alles tracebar.
Alles erweiterbar ohne Kernel-Hack.

Codex should check for each change whether it supports this goal or makes dbxapp more complicated.

2. Non-negotiable targets

1. dbxapp remains PHP web runtime, not a Laravel/React/SPA reinvention.
2. DD, FD, templates, modules and client libs remain central columns.
3. Old modules must remain operational unless otherwise agreed.
4. New APIs are introduced compatible as an additional layer.
5. Direct kernel changes only if a real reusable plug point is missing.
6. myX inheritance is an official extension layer, not a stopgap.
7. State must be traceable and recoverable.
8. Conventions may help, but must be traceable.

3. Architectural objective

dbxApp Runtime
  dbxApi / Services
  dbxComponent-Stecknorm
  dbxForm
  dbxReport
  dbxGrid
  dbxDialog
  dbxWindow
  dbxWorkflow
  dbxProcess
  DD / FD
  Templates
  Module
  Client Runtime
  myX Overrides

Codex is not intended to immediately force a large base class. First, the plug-in standard in form and report proven. A real one dbxComponentBase class comes only when the common functions are stably understood.

4. Component integration standard

All larger components should understand these connections in the long term:

id
context
dd
fd
tpl
data
state
request
actions
events / hooks
render
client
trace

New methods should be short, speaking and uniform:

->dd('kunde')
->fd('kunden|edit')
->tpl('kunden|edit')
->data($data)
->action($url)
->state('kunden.edit')
->run()

Each new component should work alone and be usable in other components.

5. Module code new style

Modules should be technical, short and legible.

class kunden {
    public function run() {
        return dbx()->actions($this)
            ->default('list')
            ->run();
    }

    public function list() {
        return dbx()->report('kunden')->run();
    }

    public function edit() {
        return dbx()->form('kunde')->run();
    }
}

Advanced adaptation remains possible:

return dbx()->report('kunden')
    ->dd('kunde')
    ->fd('kunden|rpt-kunden')
    ->rows(25)
    ->search(['name', 'email'])
    ->rowEdit()
    ->rowDelete()
    ->on('format_row', [$this, 'formatCustomerRow'])
    ->run();

If Codex sees a lot of standard technical code in a module, it should be checked whether this should result in a core building block.

6. Dealing with existing modules

Existing modules are valuable because they show real requirements. They should not be blindly rebuilt.

1. Recognize actual pattern: Routing, Form, Report, Grid, JSON, State, Actions, Special Logic.
2. Identify standard behavior that belongs in the core.
3. Specialised logic.
4. Introduce new module API at pilot stations.
5. Do not remove old code as long as no compatible replacement exists.
6. In the case of a large renovation, prefer to create modules according to new methodology than patch them cosmetically.

Current patterns:

• myLKW: Routing, sync, daily shift, JSON, processes.
• myLKW list: Grid read/sort/save/delete/sync.
• myLKW report: Special report, row formatting, print columns.
• dbxUser admin: Admin Reports, Row-/Multi-Actions, Modal.
• dbxContent edit: Form-Edit Flow, Observer, Wait-State.

7. Form and report strategy

Form and report are the first core components for the new methodology.

8. Hooks and Events

Codex is designed to provide extensibility via clear hooks, not copies of large methods.

before_load
after_load
before_validate
after_validate
before_save
after_save
before_process
after_process
before_render
after_render
on_error
on_cancel

Report-specific:

format_row
row_class
before_row
after_row
row_action
before_query
after_query

Grid specific:

before_read
after_read
before_save
after_save
before_delete
after_delete
sync
json_response

Hooks must be documented, predictable and visible with trace.

9. Workflow and process work

Codex should separate workflow and process cleanly:

Workflow = fachlicher Ablauf
Process  = technische Ausfuehrung
Step     = einzelner Schritt
State    = gespeicherter Zustand

Workflows are smart, not rigid:

• Next step by state
• User decision possible
• Error treatment possible
• Resumption possible
• Abortion and pause possible

Processes must be chunkable for large amounts of data:

State laden
Pause/Cancel pruefen
Chunk verarbeiten
Fortschritt speichern
Status ausgeben

Processes must not depend on browser life. The browser only controls and shows.

10. Persistent State

Codex is intended to treat state as a core requirement, not a by-product.

State levels:

sys      = Laufkontext des aktuellen Requests
mod      = aktive Modulinstanz
remember = laenger gueltiger Benutzer-/UI-State
session  = strukturierter Session-State
process  = persistenter Langlauf-State

Process state must contain at least:

process_id
status
current_step
cursor
processed_count
total_count
payload
result
last_error
pause_requested
cancel_requested
updated_at

When reopening dbxapp, it must be clear which work is open and where it can be continued.

11. Trace obligation

No magic at the core. Each component should be able to explain what it does:

component: report users
class: dbxReport / myReport / module custom class
module: dbxUser_admin
dd: dbxUser
fd: dbxUser_admin|rpt-users
tpl: dbxUser_admin|report-users
state: dbxUser_admin.report.users
actions: row_edit,row_delete,multi_delete
hooks: format_row,before_query
client: report.js/grid.js

When Codex introduces conventions, the trace must show the concrete resolution.

12. Implementation order for Codex

1. Before making changes, read relevant docu: RAD concept, system document, this file, roadmap.
2. Existing classes and module patterns check before new abstraction is built.
3. Prefer small compatible API supplementation.
4. A pilot module or a clear use case first.
5. Trace and Doku are thinking about new building blocks.
6. Perform tests or syntax checks where possible.
7. No large migration without explicit release.

13. First concrete work packages

1. dbxApi: Factory methods for db(), tpl(), Form(s), Report(s) design.
2. dbxForm: public Setter/Fluent-Methoden for DD, FD, TPL, Action, Data supplement.
3. dbxReport: Complement public methods for fields, query, rows, sort, actions.
4. Introduce trace structure for Form/Report.
5. Prepare dbxAdmin session list as a report pilot.
6. Prepare dbxUser admin Group Form as Form Pilot.
7. analyze myLKW list as grid pilot and derive new grid requirements.
8. dbxProcess-DD/Tabelle, but only implement it after consultation.

14. What to Avoid Codex

• Not a complete rewrite.
• No new external framework as core replacement.
• No removal of old API paths without release.
• No static, inflexible workflows.
• No hidden automatic resolution without trace.
• Do not push any technical logic into the kernel.
• No large module migrations without pilot and decision.

15. Decision-making questions before major conversions

1. Is this a general building block or just a domain case?
2. Can it be solved via DD, FD, Template, Hook or myX?
3. Are old modules still running?
4. Is the new way easier for module authors?
5. Is the process traceable?
6. Is State neatly stored and recoverable?
7. Is browser closing safe?
8. Does this change need to be discussed beforehand?

16. Target status

dbxapp should work for three groups at the end:

17. Note for Codex

dbxapp ist kein Puzzle und kein Zauberkasten.
dbxapp ist eine klare LEGO-RAD-Runtime.

Der Kern setzt die Stecknorm.
DD, FD und Templates beschreiben die Anwendung.
Komponenten fuehren vorhersehbar aus.
Hooks und myX machen alles erweiterbar.
State macht Arbeit wiederherstellbar.
Das UI darf glaenzen.