System

Registers a category of secured artifact.

Represents one secured artifact inside an object type.

The status is one of:

Grants a Role a set of permissions on a single ACL Object Identity. The combination (aclObjectIdentity, role) is unique.

All five permission flags are independent booleans (GBoolean); a missing flag is treated as false.

SYS_ACL_Bootstrap is invoked the first time the default user signs in, through DefaultAclAuthorizationReaderService.getAclUserDetails. It chains the bootstraps of the Localization (sys.loc) and User (sys.usr) submodules and then runs the ACL bootstrap (AclBootstrapService.bootstrap):

The constants used during bootstrap are defined in SYS_ACL_Constant:

AclObjectTypeImportService.importAclObjectIdentities(hasTrace, aclObjectType) discovers UI page classes by reflection (AclReflectionService.findUIPageClassNamesInPackage) within the package configured on the object type. For every discovered class:

The method returns the number of newly-created identities. It is also invoked from the UI through the aclImportObjects action on the ACL Object Type view model.

AclWriterService.validateAclObjectIdentities walks every ACL Object Identity and tries to load its Class Name:

The method returns the count of identities marked Invalid. It is invoked from the UI through the aclValidateObjects action on the ACL Object Type view model, which then renders either a success message or an error message containing the invalid count.

AclReaderService.getUserRoles(user) returns the union of:

Roles are returned as their codes (strings).

DefaultAclAuthorizationReaderService answers the security layer’s authorization questions. See the Public API section for the contract it implements; the underlying logic combines ACL Entry rows for the user’s roles with a logical OR per permission flag — a permission is granted if any of the user’s roles grants it.

Both classes are Spring @Service beans kept as cross-module extension points but currently expose no operations. Other modules that need ACL behavior reach in through the AclAuthorizationService contract or the view model actions described below.

DefaultAclAuthorizationReaderService implements io.venlo.frame.server.api.AclAuthorizationService and is the public entry point for the framework’s security layer.

SAclObjectTypeViewModel exposes two actions on the ACL Object Type page; both surface as toolbar buttons.

title: "Dynamic Forms (FRM)" ---

Top-level category that groups related schemas (for example "marketing", "trade").

The structural definition of a record type. A schema belongs to a DomainSchemaType and owns an ordered set of schema fields. At runtime it is converted to an io.venlo.domain.dictionary.DictionarySchema so the framework can read, write, and validate values.

One field of a schema. It binds a DomainProperty for typing rules and adds schema-specific concerns such as ordering, labels, mandatory/optional status, and LLM-assist prompts.

The lookup DomainSchema.getField(code) returns the schema field for a given field code, or raises a business exception if it does not exist.

A reusable typed value descriptor. Multiple schema fields can share the same property to keep typing rules consistent across schemas.

An allowed value for an enumerate property. Options also carry an optional LLM prompt that helps an AI assistant pick the option for a field.

A unit attached to numeric or text properties to clarify what the value represents (for example "kg", "%", "min").

A user-interface layout that captures data for one schema. A form has one or more sections, which can themselves nest.

A section within a form — visually a fieldset/group. Sections can be nested via parentFormSection.

One field placement inside a section. It points at a DomainSchemaField; the section’s order plus fieldNumber determine where it appears on screen.

A table layout used to list records of a schema.

One column placement within a grid.

A concrete data instance for a schema. The values are stored as JSON in recordValue; the schema interprets the JSON into typed values when the record is read.

DomainSchemaConverter.toDictionarySchema(…​) (exposed via SYS_FRM_Util.toDictionarySchema) converts a DomainSchema into a Venlo DictionarySchema. For each schema field it derives a typed ValueTypeMeta from the field’s DomainProperty — for example, String properties become a StringMeta carrying the property’s length and upper-case flag, and Decimal properties become a DecimalMeta carrying precision, scale, and rounding mode. The resulting DictionarySchema is what the rest of the framework uses to read, write, and validate record values.

Reference (R) properties are not currently convertible and raise an internal exception if encountered; they are reserved for future cross-entity references.

DomainRecordWriterService.createDomainRecord(schema, recordValue) creates a new DomainRecord with a fresh GUID, links it to the supplied schema, and persists it. The caller is responsible for producing a JSON DomainRecordValue whose keys match the schema’s field codes.

Two helper classes simplify reading and writing record-set JSON in service code:

DomainSchemaReaderService.createDomainSchemaFieldAssistPrompt(…​) is the entry point for building the prompt that asks an LLM to fill a single field of a record, using the field’s llmPromptPrefix, llmAssistPrompt, and any enumerate option’s llmOptionPrompt. The current implementation returns an empty string and is a placeholder for the upcoming LLM-driven form-filling feature.

Read-side facade for other modules.

Write-side facade for other modules.

Static utility for converting a DomainSchema to a Venlo DictionarySchema. Used wherever the framework needs to render or validate record values for a schema.

Currently contains no constants.

The submodule defines view models (DomainSchemaViewModel, DomainPropertyViewModel, DomainFormViewModel, …​) for the standard CRUD pages, but does not declare any custom UI actions. There are no buttons specific to this submodule beyond the default toolbar.

title: "LLM Integration (LLM)" ---

The umbrella product/feature whose agents share a base system prompt.

A configured caller within an application; runs actions to achieve a goal.

Classification used to group agents (for example "human", "autonomous", "review").

A repeatable LLM task. An action bundles all the metadata Spring AI needs to build a ChatClient: the model, configuration, persona, memory strategy, prompt text, plus the link tables for schemas, skills, tools, MCP clients, document collections, and advisors.

The hand-written entity adds the helpers getInputSchemas() (returns input/memory schemas) and getOutputAgentSchema() (returns the single output schema or raises a business exception if zero or many exist).

Classification with an optional global constraint prompt that is added to every action of that type.

Links an action to a DomainSchema for either input, output, or memory data, with cardinality and optional UI hints.

A validation rule enforces that, when a domainForm or domainGrid is given, it must reference the same domainSchema as this row.

These are pure link tables that attach reusable capabilities to an action.

Persona provides the voice/role prompt fragment.

Skill is a reusable capability prompt added to actions through LlmActionSkill.

Tool maps a Spring bean to a function the LLM can call.

MCP client describes a Model-Context-Protocol server connection that exposes one or more tools.

Advisor declares a Spring AI advisor bean that can be inserted into the chat-client pipeline of an action.

These three entities configure RAG sources.

Memory strategy controls how chat history is retained for a conversation.

Sampling, temperature, token-limit, and retry settings applied when building chat options.

Model identifies a specific LLM offered by a provider; provider is the vendor (Anthropic, OpenAI, …​).

Lists what a model is capable of (link table on the model, keyed by capability type).

One running instance of an agent calling an action. The conversation aggregates its messages, attachments, and tool calls and tracks lifecycle, finish reason, token usage, estimated cost, and any error detail.

One entry in a conversation’s transcript. Messages are recorded as immutable events ordered by messageSequence.

A file attached to a message (image, document, …​). Stored as an immutable event.

A function call the LLM emitted during a message.

LlmPromptAssemblyService builds the system prompt that is sent on every conversation. It concatenates contributions from the agent’s application, the agent itself, the action’s persona, every linked skill, every linked MCP client, the schema-prompt block (input/output data structures), and finally the action’s own prompt. Each contribution comes from IsPromptContributor.getPromptContribution() — implemented by LlmApplication, LlmAgent, LlmPersona, LlmSkill, McpClient, and LlmAction. Skills and MCP entries get short labels (Your skill: …​, Available tool '<name>': …​) before their text so the LLM can distinguish them.

LlmActionSchemaPromptService walks the action’s LlmActionSchema rows and produces an "Input data structure:" / "Output data structure:" block describing each schema’s fields. It is used as one segment of the assembled system prompt so the model knows the shape of the data it must consume and produce.

LlmChatOptionsFactory translates an action’s LlmConfiguration into a Spring AI ChatOptions (model name, max tokens, temperature, top-K, top-P, frequency penalty, presence penalty). Optional values are only set on the builder when present.

LlmChatClientFactory is the central wiring point. For each conversation it produces a Spring AI ChatClient configured with: the model bean for the action’s model, the assembled system prompt, the chat options, the resolved tool callbacks plus a per-conversation AskUserQuestion tool, the resolved advisors (action advisors + RAG advisors + a chat-memory advisor when a memory strategy is set), and any MCP tool callbacks. The resulting client is what LlmConversationService calls into.

LlmToolCallbackResolver looks up each LlmActionTool by its llmToolBeanName in the Spring application context and verifies that the bean is a ToolCallback. It supports an exclude set so the per-conversation AskUserQuestion callback can be inserted separately.

LlmAdvisorResolver reads LlmActionAdvisor rows ordered by llmAdvisorOrder and looks up each llmAdvisorBeanName in the Spring context. The resulting list of Advisor instances is added to the chat-client pipeline.

LlmDocumentCollectionResolver walks the action’s LlmActionDocument rows. For each linked LlmDocumentCollection it looks up the matching VectorStore bean (by the vector store’s code) and creates a QuestionAnswerAdvisor configured with the collection’s similarity threshold and result count. The default top-K is 4 when not specified on the collection.

LlmMcpClientResolver opens (and caches) one McpSyncClient per McpClient entity, choosing the transport (stdio, streamable HTTP, or SSE) based on mcpTransportType and the mcpConnectionUrl. Each connected client is wrapped in a SyncMcpToolCallbackProvider whose tool callbacks are merged into the chat client. Connections are kept across conversations and closed during shutdown.

LlmMemoryService materializes a ChatMemory per conversation based on the action’s LlmMemoryStrategy. FULL strategy uses an unbounded MessageWindowChatMemory; any other strategy uses a window of llmMemoryWindowSize messages. Memories are cached by conversation id and can be cleared explicitly.

LlmConversationService is the primary entry point for running an action. startConversation creates a LlmConversation row with a fresh GUID. sendMessage / sendMessageWithAttachments records the user message (and any attachments), flips the conversation to RUNNING, builds a chat client, and calls the model. On success it records the assistant message, persists every emitted tool call, captures token usage and estimated cost (using the model’s input/output token prices), and marks the conversation COMPLETED with the appropriate finish reason. On failure it records the error detail and marks the conversation FAILED.

LlmAskUserQuestionService together with ErpAskUserQuestionHandler implements the AskUserQuestion pattern. When the LLM calls the AskUserQuestion tool, the handler thread blocks on a CompletableFuture for up to five minutes while the conversation status is set to WAITING and a question message (role QU, falling back to TO if the generator has not yet produced the QU code) is persisted. A separate API call (submitAnswers) resolves the future and unblocks the handler so the LLM can continue. Each conversation gets its own handler instance, bound to its conversation id.

Read-side facade used by other modules and the UI.

Write-side facade used by other modules and the UI.

IsPromptContributor is the public seam for entities that contribute a fragment to the assembled system prompt. The submodule itself implements it on LlmApplication, LlmAgent, LlmPersona, LlmAction, LlmSkill, and McpClient. Other modules that introduce their own LLM-aware entities can implement the same interface to plug into prompt assembly.

ErpAskUserQuestionHandler implements the framework’s io.venlo.frame.server.ai.tools.AskUserQuestionHandler. It is constructed per conversation by LlmChatClientFactory and forwards the LLM’s structured question payload to LlmAskUserQuestionService.waitForUserAnswers, blocking until submitAnswers is called.

The submodule defines view models for the standard CRUD pages on every entity but does not declare any custom UI actions. Conversations, messages, tool calls, and attachments are surfaced as event streams under their parent conversation.

title: "Localization (LOC)" ---

A monetary unit. Used as the default currency on countries and as the trading currency throughout the ERP.

A spoken/written language. Used to localize user-facing text and as the default language on countries and locales.

A high-level group of countries.

A nation-state. Carries the defaults for currency, language, region, and unit-of-measure system, plus the trade and AML markers used when transacting with parties from this country.

A subdivision of a country (state, province, …​).

A language/country/variant combination used to format text, numbers, and dates for users.

A named time zone keyed by a short code and resolved to a ZoneId.

SYS_LOC_BootstrapApi.bootstrap runs at system bootstrap and idempotently inserts a baseline set of localization records when they are missing: a default currency, language, region, country, locale, and time zone. The values are the constants on SYS_LOC_Constant (see Defaults below) and existing records are never overwritten — the bootstrap only creates what is not already there. Other modules can rely on these defaults being present after startup.

CurrencyReaderService exposes both an optional and a mandatory currency lookup by code. The mandatory variant raises a business exception when the code does not exist and is the seam used by other modules that cannot proceed without a known currency. All other entities are read directly through their generated readers.

Read-side facade.

Currently an empty placeholder — no cross-module write operations are exposed. Other modules treat localization data as read-only at runtime.

Single entry point bootstrap(HasTrace) — see Bootstrap of default reference data above. Called by the system-wide bootstrap sequence, not by end users.

The submodule defines view models for the standard CRUD pages on every entity but does not declare any custom UI actions. Localization data is maintained through the default toolbar.

title: "Scripts and Styles (SCR)" ---

A reference type that names the scripting language used by the scripts of this type.

A named source-code fragment. The hand-written entity recalculates biStatus whenever the script is marked compilable or archived, so the UI always shows the current state without a separate refresh.

A named pointer to a CSS class. Other modules reference styles by their code so the visual styling can be changed without touching business code.

ScriptEvaluateService.compile compiles a script’s source through a single shared GraalVM Context configured with js and allowAllAccess(true). On success the service stores the compiled Value under the script’s code in the in-memory cache and flips the script’s compilable flag to true; on a PolyglotException the flag goes to false and the exception is captured in the returned CompilationResultDto. The service never throws compilation errors itself — callers that need to fail loudly read CompilationResultDto.getException().

The cache is an in-memory map keyed by Code12. compile consults it before re-compiling when called with useCache = true. The cache can be cleared per-script (clearCache(Code12)) — used by the Compile UI action so a fresh compile follows a source-code change — or entirely (clearCache()).

ScriptEvaluateService.executePredicate compiles the script (using the cache by default) and then invokes the resulting Value with the supplied arguments. The single-argument variant returns a Boolean; the typed variant accepts a target class so callers can request any type the JavaScript expression returns. Compilation or runtime errors are wrapped in an internal business exception that names the script’s code.

The Compile action on ScriptViewModel clears the cache entry for the script being viewed, recompiles its source from the entity, and shows either a success message or the captured PolyglotException in the desktop message area. The action is always enabled.

This submodule does not expose a dedicated query API class. Scripts and styles are read directly through the standard generated readers when needed, and the only outward-facing call — predicate evaluation — sits on the command API instead.

Cross-module facade. Both methods delegate to ScriptEvaluateService.executePredicate with useCache = true.

IsCompilable is the seam used by the compile pipeline. It is implemented by Script (via the entity itself) and by ScriptViewModel (via the view model). Other modules that introduce their own script-like entity can implement the same interface to plug into ScriptEvaluateService.compile and ScriptCompileUtil.compile without inheriting from Script.

title: "Units of Measure (UOM)" ---

Immutable record holding a value paired with a unit-of-measure code. Carries assertion helpers (assertHasUomType, assertHasUomTypeAndExponent) so callers can verify that a quantity is in the expected dimension before using it.

Quantity that additionally tracks a piece count. Used when an item is sold by weight or volume but also exists as discrete units (for example "5 kg comprising 20 pieces"). toSiQuantity() strips the piece count when only the dimensional part is needed.

A parsed two-component compound unit such as kg/m3 or g m^-3. Instances are cached by uomCode for the lifetime of the JVM since parsing is pure.

A compound unit paired with a numeric value, used as the result of compound conversions.

A single parsed unit, optionally prefixed and exponentiated. Cached by uomCode.

A single unit paired with a numeric value, used as the result of single-unit conversions.

Enum listing every unit the submodule recognises (PCS, AMPERE, CANDELA, KELVIN, CENTIGRADE, GRAM, TONNE, METER, LITER, MOLE, SECOND, plus imperial: FAHRENHEIT, OUNCE, POUND, STONE, TON, INCH, FOOT, YARD, FURLONG, MILE, FLUID_OUNCE, GALLON). Each value carries its conversion factor to its base unit, its base-unit signature, and the symbols accepted on parse.

The base-unit fingerprint of a SiUom. Two units are convertible only when their signatures match. A signature is a list of (SiUomBase, exponent) items — typically one item, with two used for compound-derived units.

Enum of the nine base units the system reduces everything to. Each base value carries a symbol and the dimensional SiUomType it represents.

Enum naming the physical dimension a base unit measures.

Enum listing the SI prefixes recognised on parse, with their decimal multipliers and symbols.

METRIC or IMPERIAL — used by callers that want to pick a unit set for a country or product class.

ADD, SUBTRACT, MULTIPLY, DIVIDE — selects the arithmetic combination performed by SiUomCalculationUtil.calculateQuantities.

SiUomSingleUomUtil converts a SiQuantity (or a raw value/uomCode pair) between two single-unit codes. The conversion goes through the base unit: the source value is reduced to its base via the unit’s factorToBaseUnit and prefix multiplier, then expanded into the target. convertToSiUomIfConvertable returns null instead of raising when the dimensions do not match — useful when callers want to fall through to an alternative.

SiUomCompoundUtil.convertToSiUomBase parses a compound unit code such as kg/m3 into two SiUomSingle components, requires that the first component has a non-negative exponent and the second a non-positive exponent, and reduces the value to the equivalent base-unit compound (e.g. g/m3). Compound units with shapes other than two components raise a business exception.

SiUomCalculationUtil.calculateQuantities adds, subtracts, multiplies, or divides two SiQuantity values whose base units agree, returning the result expressed in a caller-supplied target unit. Both quantities are first reduced to their base unit so that, for example, 1 kg + 500 g returns the expected mass. Division by zero raises a business exception.

The same utility class hosts higher-level helpers used by the trade and inventory flows:

SiUomUtil.assertHasUomTypeAndExponent and the matching helpers on SiQuantity raise a business exception when a quantity’s dimension or exponent does not match the expected one. They are used pervasively at the entry of every calculation helper so failures point at the offending input.

SiUomPreprocessor rewrites convenience forms before parsing: it splits a numerator/denominator compound, expands trailing-digit forms (m2 → m^2, m3 → m^3), and applies a negative exponent sign to the denominator. The parsed forms feed both SiUomSingle.of and SiUomCompound.of, both of which cache their results.

The submodule does not provide a query or command API class. Other modules call the static utility classes directly:

The submodule does not expose any UI; it is consumed exclusively from server-side code. There are no view models or actions to document.

There is no bootstrap class — the recognised units, prefixes, and base units are declared as Java enums and are available from JVM start without any database state.

title: "Users, Roles and Groups (USR)" ---

A classification of users.

A user account.

A named permission grouping. Used by the acl submodule to grant object access; this submodule only stores the role identities.

A group whose members all share its assigned roles.

Direct role assignment to an individual user.

Role attached to a group. Every member of the group inherits the role.

User membership in a group.

SYS_USR_BootstrapApi.bootstrap runs at system bootstrap and idempotently provisions a baseline set of records when they are missing: a default UserType (001), a default User (admin), a default UserGroup (001), a default Role (sys_ope), and the UserGroupMember and UserGroupRole rows that bind the admin user to the group and the role to the group. Existing records are never overwritten. The bootstrap pulls the default locale and time zone from sys.loc and fails fast if those are missing.

The defaults that govern this step are constants on SYS_USR_Constant:

UserReaderService.getLoggedInUser reads the current username from the Spring Security context (VenloContext.getUserDetails()) and looks up the matching User row. It raises a business exception when the username does not resolve to a user — used by every action that needs to attribute work to "the current user" (audit fields, theme preferences, etc.).

BatchUserReaderService provides the technical user the system runs as for background jobs that have no interactive session. loginBatchJobUser registers the configured batch-job credentials with VenloContext.setBackgroundUserDetails; getBatchJobUser returns the corresponding User entity. Credentials come from SystemSettingService, which reads the erp.sys.usr.batchJobUserName and erp.sys.usr.batchJobPassword properties and trims them.

UserPreferenceViewModel exposes two actions that flip the dark-theme preference on the currently logged-in user. Both actions are always enabled and persist immediately — the user does not need to save the preference page.

Two view models render a dynamic checkbox matrix so administrators can manage role and group bindings without scrolling through long lists of link rows:

Read-side facade.

Currently an empty placeholder — no cross-module write operations are exposed. User and group records are maintained through their default UI pages and the dynamic matrix view models.

Single entry point bootstrap(HasTrace) — see Bootstrap of default user, group, and role above. Called by the system-wide bootstrap sequence, not by end users.