Architecture

Module Map


index.js  (CLI entry — meow)
│
├── utils/cli.js                      flag definitions
├── utils/functions.js                capitalize, FieldTypeGeneration, deriveResourceName…
│
├── src/api/api.js                    OAuth2 + all API metadata calls
│   ├── getOAuth2Token()              client_credentials grant → config/token.txt
│   ├── MetaDataEntityList()          fetch entity fields + types from OpenAPI
│   ├── SerializationShowFields()     fetch show-page serialization group
│   ├── SerializationListingFields()  fetch listing serialization group
│   ├── RequiredFields()              fetch required field constraints
│   ├── ResourceNameList()            fetch resource name (API slug)
│   └── checkCacheExists / loadCachedMetadata()
│
├── src/core/version-manager.js       pure version bookkeeping
│   ├── getNextVersion / getLatestVersion / getAllVersions
│   ├── saveVersionData / loadVersionData
│   ├── createVersionedChangesTemplate()  build fresh changes.json
│   └── mergeChangesTemplates()           merge old changes → new version
│
├── src/core/changes-engine.js        apply changes.json customizations to raw data
│   └── applyChanges()
│
├── src/core/changes-preview.js       dry-run + field validation
│   ├── previewChanges()
│   └── validateChanges()
│
├── src/json/
│   ├── json-generator.js             JSON layer creation
│   │   ├── generateJson()            fetch → data.json + changes.json
│   │   └── generateJsonAll()         batch for whole bundle
│   └── json-applier.js              JSON version utilities
│       ├── checkJsonChanges()
│       ├── matchScraperFields()      legacy field matching
│       └── listJsonVersions()
│
├── src/tsx/
│   ├── tsx-generator.js              TSX layer creation
│   │   ├── generateTsx()             data.json + changes.json → index.tsx
│   │   └── generateTsxAll()
│   └── tsx-applier.js               TSX version utilities
│
├── src/templates/template-generator.js  [placeholder] token replacements
│   ├── CreateConfigFromTemplate()    copy config-template.tsx → output
│   ├── AddFQCN / AddResource / AddSelectedList
│   ├── AddFormInputs / AddFormModalInputs / AddMainColumns
│   ├── AddFilterFields / AddSideBoxs / AddDisplayFields
│   ├── AddInterfaces / AddDefaultListingFilters
│   ├── AddImportStatements()         entity-specific imports (e.g. TableNames, PropertyTypes)
│   └── DefaultListingActions / DefaultCustomActions
│
├── src/process/entity-processor.js  metadata + cache orchestration
│   └── applies INPUT_EXCLUSION_LIST, LISTING_EXCLUSION_LIST
│       builds context object passed to template-generator
│
├── src/legacy/legacy-integration.js  scraper field matching
│   ├── findLegacyData()
│   └── processFieldsWithLegacy()     similarity-score field matching
│
└── src/commands/versioned-commands.js  command handlers
    ├── handleGenerateJson / handleGenerateJsonAll
    ├── handleGenerateTsx / handleGenerateTsxAll
    ├── handleGenerateVersioned
    ├── handleExportEntity
    └── handleValidate*

Data Flow — Single Entity


1. token
   └─ api.js: OAuth2 client_credentials → config/token.txt

2. gen:json
   ├─ api.js: fetch fields, types, serialization groups, required constraints
   ├─ entity-processor.js: apply exclusion lists, detect field types
   ├─ version-manager.js: determine next version (v0, v1…)
   ├─ version-manager.js: createVersionedChangesTemplate() → changes.json
   └─ write: config/versioned/json/{Bundle}/{Entity}/{vN}/
               ├── data.json       (raw snapshot)
               └── changes.json    (editable template)

3. [edit changes.json]

4. gen:tsx
   ├─ version-manager.js: load data.json + changes.json
   ├─ changes-engine.js: applyChanges() → merged field sets
   ├─ template-generator.js: copy config-template.tsx, replace [placeholders]
   └─ write: config/versioned/tsx/{Bundle}/{Entity}/{vN}/index.tsx

5. exportEntity
   └─ copy index.tsx → destination folder in your frontend project

Incremental Generation Flow

When the API schema changes, pass --fromVersion=vN:


gen:json --fromVersion=v0
  ├─ load v0/data.json + v0/changes.json
  ├─ fetch fresh metadata from API
  ├─ version-manager.js: mergeChangesTemplates(old, newTemplate)
  │    preserves: selected fields, ordering, validation, helpers
  │    removes:   fields no longer in API
  │    adds:      new API fields to appropriate sections
  └─ write v1/data.json + v1/changes.json

Environment Setup

Create a .env file in the project root. Each --bundleCrud value reads its own vars:


# PHPReaction (phprCrud)
PHPR_OAUTH_CLIENT_ID=your_client_id
PHPR_OAUTH_CLIENT_SECRET=your_client_secret
PHPR_OAUTH_TOKEN_URL=https://demo.phpreaction.com/oauth/token
 
# Config (configCrud)
CONFIG_OAUTH_CLIENT_ID=
CONFIG_OAUTH_CLIENT_SECRET=
CONFIG_OAUTH_TOKEN_URL=
 
# Ticket (ticketCrud)
TICKET_OAUTH_CLIENT_ID=
TICKET_OAUTH_CLIENT_SECRET=
TICKET_OAUTH_TOKEN_URL=
 
# Account (accountCrud)
ACCOUNT_OAUTH_CLIENT_ID=
ACCOUNT_OAUTH_CLIENT_SECRET=
ACCOUNT_OAUTH_TOKEN_URL=

Alternatively run ./index.js token --devUsername=... --devPassword=... to fetch a bearer token interactively — saved to config/token.txt and used automatically by all subsequent commands.

File Structure


frontend-components-crud-react-generator/
├── index.js                          ← CLI entry (phpr / phpcrt commands)
├── src/
│   ├── api/
│   │   └── api.js                   ← OAuth2, metadata fetching
│   ├── commands/
│   │   └── versioned-commands.js    ← all command handlers
│   ├── core/
│   │   ├── version-manager.js       ← versioning, changes.json template
│   │   ├── changes-engine.js        ← apply customizations to data
│   │   └── changes-preview.js       ← preview & validation
│   ├── json/
│   │   ├── json-generator.js        ← JSON layer generation
│   │   └── json-applier.js          ← JSON version management
│   ├── tsx/
│   │   ├── tsx-generator.js         ← TSX config generation
│   │   └── tsx-applier.js           ← TSX version management
│   ├── templates/
│   │   └── template-generator.js   ← populates [placeholder] tokens
│   ├── process/
│   │   └── entity-processor.js     ← metadata processing & caching
│   └── legacy/
│       └── legacy-integration.js   ← scraper data matching
├── scripts/
│   ├── generate-phpr-entities.sh       ← batch shell script (PHPReaction)
│   ├── generate-config-entities.sh     ← batch shell script (Config)
│   ├── generate-ticket-entities.sh     ← batch shell script (Ticket)
│   ├── generate-account-entities.sh    ← batch shell script (Account)
│   ├── generate-table-names.js         ← writes config/tableNames.js
│   └── generate-entity-names.js        ← writes config/entityNames.js
├── config/
│   ├── config-template.tsx             ← TSX skeleton with [placeholder] tokens
│   └── versioned/                      ← all generated output (re-generatable)
│       ├── json/                       ← JSON layer per entity/version
│       └── tsx/                        ← TSX layer per entity/version
└── utils/
    ├── cli.js                          ← all CLI flag definitions
    └── functions.js                    ← capitalize, FieldTypeGeneration, etc.

Everything under config/versioned/ is generated output. Commit only config/config-template.tsx and config/propertyTypes.js — the versioned files can always be regenerated.