Overview
App generator
The app generator builds a complete WUIC app (tables, routes, columns and lookups, menu, roles and permissions, views, translations, reference data and demo data) from a plain-language description, from tables of an existing database or from an Excel/CSV file, and changes installed apps on request. The model designs a blueprint (JSON with a versioned schema); a deterministic compiler turns it into a .wuicpkg package that is installed with the metadata lifecycle pipeline: preview, plan, apply, rollback and promotion work for generated apps too. The model never writes to the database.
When to use it (use cases)
- Start from scratch: "fleet management: vehicles, drivers, maintenance, refuelling; the fleet manager does everything, drivers record their own refuelling".
- Put an interface on an existing database without touching its tables ("adopt the tables" mode).
- Turn an Excel sheet into normalized tables (repeated values become reference tables) and import its rows.
- Evolve an installed app in plain language ("add the website to the teachers"), including apps not created by the generator, without losing the changes made by hand in the designers.
- Verify an app with a test suite generated from the blueprint (API level and UI level).
Who can use it
Only the superadministrator, checked against the database on every request and on every model turn. The page is the system menu entry "New app" under Administration (/app-generator). The APIs are under api/app-generator/*.
How it works
1. Session: plain language, from database, from Excel or "change an installed app". For database and Excel, blueprint version 1 is a deterministic draft (no model); for a change it is the blueprint of the last installation or the one rebuilt from the installed app (reverse blueprint).
2. Conversation: the model reads with read-only tools (compiler capabilities, existing routes, database catalog, Excel profile, validator, dry-run preview), asks at most 3-5 structural questions (ask_user) and proposes a blueprint with propose_blueprint. The service validates it again: an invalid blueprint goes back to the model with the errors and their path and never becomes a version.
3. Review: the blueprint can also be edited by hand in the central panel (entities and fields, relations, role/permission matrix, menu); every save is a new validated version, which the model respects on the next turn.
4. Preview and installation: lifecycle plan (DDL that will run, artifacts created or changed, warnings), then "Install" (apply with the plan hash). After installation: link to the first menu entry, list of the codeHooks to complete, "Verify app" (API suite) and, for Excel, row import.
The blueprint
{
"schemaVersion": 2,
"app": { "key": "helpdesk", "name": "Helpdesk", "languages": ["it", "en"], "defaultLanguage": "it", "menuRoot": "Helpdesk" },
"entities": [
{ "key": "ticket", "label": { "it": "Ticket", "en": "Ticket" }, "table": "hd_ticket",
"fields": [
{ "key": "id", "type": "int64", "pk": true, "identity": true },- Logical types:
string,text,int32,int64,decimal,money,bool,date,datetime,time,guid,email,url,phone,enum,ref,user. Each type has a fixed mapping to the physical type of the 4 DBMSs. - Declared rules (
rules, closed kinds):comparebetween two dates or two numbers,emptyWhen/requiredWhenwith a condition on an enum or a reference,independent. They become CHECK constraints, record validation in the grid and constraints on the demo data. An entity with two or more dates must declare how each of them relates. - Enum labels (
valueLabels) in every app language and lookup text in views (display): the validator requires them from the model, so users never see raw codes. - Adopted entities (
adopt: true): existing tables; the package carries no DDL and no data, metadata only. - `codeHooks`: custom code is not generated; it stays as a brief to complete with WUIC Assistant or Claude Code.
Dashboards and workflows
The model proposes them when the description asks for them (an overview, totals, a cycle of states with who may do what); they go through the validator like the rest and are installed by the lifecycle import.
"dashboards": [ { "key": "overview", "label": { "en": "Ticket overview" }, "tiles": [
{ "kind": "kpi", "entity": "ticket", "measure": { "fn": "count" }, "filter": { "field": "priority", "op": "neq", "value": "low" } },
{ "kind": "chart", "chart": "bar", "entity": "ticket", "groupBy": "priority", "measure": { "fn": "count" } },
{ "kind": "list", "entity": "customer" } ] } ],
"menu": [ { "key": "overview", "label": { "en": "Overview" }, "dashboard": "overview" } ],
"workflows": [ { "key": "lifecycle", "entity": "ticket", "stateField": "status",
"transitions": [ { "from": "open", "to": "in_progress", "roles": ["operator", "manager"] },- Dashboards:
kpitiles (one number: count, or sum/avg/min/max of a numeric field),chart(bar, line, pie, doughnut grouped by an enum, reference, boolean or text field) andlist, with an optional filter (eq/neq,gt/gte/lt/lteon numbers and dates). The server computes the values on the rows the user can see (permissions and row filters); the menu item goes to the roles that see every tile entity. - Workflows: the state field is an enum or a reference to a
referenceentity with its data; each transition lists the roles that run it (they must view and update the entity), the first one starts from the initial state. The state changes only through the transitions (the server rejects direct edits, wrong source and target states and inserts in a state other than the initial one); SLAs notify a role (notify_role) or move the record to another state (escalate_state). The workflow runner has its own menu item. - The generated suite tests the read of every tile per role and, for every transition and role, the allowed or rejected action.
Richer dashboards
Optional tile properties; a blueprint that does not use them compiles as before, except for the board layout described below.
| Property | Tile | Effect |
|---|---|---|
period | chart | with groupBy on a date field: groups by day, month, quarter or year (day, month, quarter, year), computed by the server and in time order; required when groupBy is a date |
measures | chart bar or line | 2 to 4 series on different fields (count uses the key), each with its own label; instead of measure |
filters | all | 1 to 5 conditions, all true (AND); instead of filter |
width | all | full, half (default) or third; tiles follow the order of the list |
format | kpi | currency (ISO 4217 code, e.g. EUR) or unit (short text, e.g. h), decimals 0 to 6; the browser formats the number in the user's language |
{ "key": "vendite", "label": { "it": "Sales trend" }, "tiles": [
{ "kind": "kpi", "entity": "vendita", "width": "third", "label": { "it": "Online revenue 2026" },
"measure": { "fn": "sum", "field": "importo" }, "format": { "currency": "EUR", "decimals": 2 },
"filters": [ { "field": "canale", "op": "eq", "value": "online" }, { "field": "data", "op": "gte", "value": "2026-01-01" } ] },
{ "kind": "chart", "chart": "line", "entity": "vendita", "width": "full", "label": { "it": "Sales by month" },
"groupBy": "data", "period": "month",
"measures": [ { "fn": "count", "label": { "it": "Vendite" } }, { "fn": "sum", "field": "importo", "label": { "it": "Importo" } } ] },- The server computes the period (first day of the period) on SQL Server, MySQL, PostgreSQL and Oracle; the browser writes the label (short month, quarter as
Q4 2026). - Without a
labela series is named after the function and the field in the app language (e.g. "Sum of Amount"). - The validator rejects:
groupByon a date withoutperiod,periodon a field that is not a date, two measures on the same field, several measures in a pie or doughnut,filterandfilterstogether,formatoutside a kpi. - Layout: the board fills the space below the menu without clipping anything. Rows with only KPIs are compact; rows with charts or lists share the remaining height equally (at least 180px, 240px with a list, which scrolls inside with the paginator always visible); the chart follows the tile height, also when the window is resized. If the rows do not fit (short window) or the board is narrower than 960px (tablet, phone: tiles stack at full width) the board scrolls inside. Dashboards drawn by hand in the designer do not change.
What the compiler generates
| Blueprint element | Artifacts in the package |
|---|---|
| entity | data-table (safe DDL per DBMS, 7 audit columns + logical delete) and app-route: the route is created by scaffolding the new table, as from the UI |
ref field | FK + lookupByID column towards the target route (friendly value/text fields) |
enum | dictionary with translated labels and CHECK on the values |
reference entity + referenceData | table and rows with preserved IDs (upsert by natural key) |
kanban / calendar / chart views | archetypes in the route md_props_bag |
grants | roles and permissions per route; rowFilter → "inserting user" restriction |
menu | entries <app> / <app>__<item> with labels app.<app>.menu.* |
| labels, values, rules | translations in the app.<app>.* namespace |
demoData | deterministic rows (fixed seed) consistent with types, references and rules |
dashboards | dashboard artifact (board <app>_<key>, tiles with their read in md_props_bag) and menu item |
workflows | workflow artifact (graph, one step per state, one action per transition, direct edits of the state forbidden, SLAs with the scheduler job) and runner menu item |
| the whole blueprint | test-suite artifact with the generated API suite |
Same blueprint and same DBMS ⇒ same package (identical hash); uids are UUID v5 from app key + element key, so a regeneration updates the same artifacts.
From an existing database ("adopt the tables")
GET api/app-generator/catalog?schema= lists tables and views of the data database (framework tables excluded); the session { "inputKind": "db", "tables": ["Purchasing.Suppliers", ...] } creates the draft: FKs → references with the descriptive field, technical columns hidden when the database fills them, computed columns read-only, menu per schema, a utente role to review. Adopted tables are never changed: the plan lists them as adoptedTables and checks they exist; new information about an adopted table goes into a new linked entity.
From Excel / CSV
POST api/app-generator/excel/upload (xlsx, csv, txt; 20 MB, 20 sheets, 200 columns, 100,000 rows per sheet) returns the profile: inferred types (numbers and dates in Italian format too), unique columns, lookup candidates and relations between sheets. Each sheet becomes a new entity; columns with few values become reference tables. After installation, POST api/app-generator/sessions/{id}/import-data imports the rows with the existing import: references resolved to keys, rows already present (same natural key) skipped, discards with row and reason. The model receives the profile, not the cell values, unless AppGenerator:SendSampleValues=true.
Changing an installed app
POST api/app-generator/sessions { "inputKind": "app", "appKey": "...", "menuRoots": [...] } starts from the last installed version (source installed) or, for an app not created by the generator, from the reverse blueprint rebuilt from routes, columns, lookups, permissions and menu (source reverse; what cannot be represented stays as it is and is listed as an override). The model changes only what is asked (effort AppGenerator:EditEffort).
Installation is a 3-way plan with base = last installed package of the app: changes made by hand in the designers stay, the requested ones arrive, the same property changed on both sides is a conflict resolved per property (conflict view in the wizard; installation stays blocked while conflicts are open). A new field on an already installed entity is created with an ALTER in the data phase and scaffolding of the column.
The reverse blueprint also reads dashboards and workflows back when they have the shape the generator produces; a workflow whose state references an adopted table carries the value of each state (row id) in stateValues. Boards drawn by hand, graphs with other nodes or with names outside the <app>_<key> convention stay as they are and are listed as overrides.
Generated tests
- API level (
POST api/app-generator/tests/{app}/run): for every entity and role metadata, permissions, CRUD cycle, validations (required, lengths, types, FKs, enums), row filters, reference data and menu, with two temporary users per role and marked records, removed at the end (cleanup). It refuses to run in aprodenvironment. For an existing app:POST api/app-generator/tests/installwith the reverse blueprint. Results in the "Verify app" tab of the App lifecycle page. There Create the test suite for this app (or Regenerate the suite, if it already exists) does the same for the current app without choosing anything:POST api/app-generator/tests/install-currentrebuilds the reverse blueprint from the menu seen by the user who clicks (menu and route permissions included, system entries excluded), shows notes and problems, asks for confirmation and applies the plan of the suite only. Key and name:AppGenerator:CurrentApp:Key/:Name(defaultapp/App), the same in every environment because the suite is promoted with the same key. If the app has no roles of its own (administrative roles only) the checks use the roles of the user who clicks, with full access as in reality; a suite without checks is not installed and the page says why. Below the buttons the Runs list (the last 50 of the chosen app: date, author, environment, result, duration;GET tests/{app}/runs) opens the results of a past run with a click (GET tests/runs/{runId}). - UI level (
POST api/app-generator/tests/ui, "Download UI tests" button): one.mjsfile per check (menu, grid, form with save and cleanup, kanban/calendar/chart) and the docs-driven catalog rows;scripts/docs-driven-tests/verifica-test-generati.mjs <catalog>checks their shape before a run.
Configuration (AppGenerator section of appsettings)
Model provider and key are those of the RAG chat (rag-llm-provider, rag-llm-api-key; agent-sdk = the subscription claude CLI).
| Key | Default | Meaning |
|---|---|---|
Model | claude-opus-5-5 | design model |
Effort / EditEffort | high / medium | effort for design and for changes to an installed app (also on the CLI) |
SendSampleValues / MaxSampleValues | false / 5 | sample values (Excel cells, distinct values) sent to the model only with consent |
MaxToolRounds / MaxProposalAttempts | 16 / 3 | tool rounds per turn, invalid proposals before the turn ends with an error |
TurnTimeoutSeconds / TurnTokenBudget | 300 / 1500000 | maximum time and tokens of a turn |
SessionTokenBudget | 6000000 | tokens of a session (closed turns); 0 = off |
DailyTokenBudgetPerUser | 20000000 | tokens per user per day on generator sessions; 0 = off |
MaxPendingTurnsPerUser / MaxTurnsPerMinutePerUser | 1 / 6 | turns in progress and per minute per user; 0 = off |
API
| Method | Endpoint | Notes |
|---|---|---|
| GET | api/app-generator/schema | JSON schema of the blueprint |
| POST | api/app-generator/validate / compile / install | blueprint in the body; install = lifecycle plan, apply is api/meta-lifecycle/promotions/{id}/apply |
| GET / POST | api/app-generator/catalog, draft, reverse | catalog, draft from tables, reverse blueprint |
| POST | api/app-generator/excel/upload, excel/draft, excel/import | Excel/CSV |
| POST / GET | api/app-generator/sessions, sessions/{id} | sessions (nl, db, excel, app) |
| POST | api/app-generator/sessions/{id}/messages | asynchronous turn: "pending" reply, outcome on the message and in the bell |
| GET / PUT | api/app-generator/sessions/{id}/blueprint | current version; PUT = validated manual edit |
| GET | .../blueprint/versions, .../blueprint/diff?from=&to= | versions and differences |
| POST | .../package, .../install, .../import-data | package, plan (3-way for changes), row import |
| POST / GET | api/app-generator/tests/* | API and UI suites (see above) |
Typed errors: errors.app_generator.blueprint_invalid, input_invalid, message_required, session_not_found, no_valid_blueprint, proposal_invalid, excel_invalid, upload_not_found, tests_prod_forbidden, test_suite_not_found and, for the limits (429, args.max), turn_in_progress, rate_limited, session_budget, daily_budget. Model errors (refusal, time, provider, not configured) use the errors.nl_query.* codes.
Security
- The model reads with read-only tools and proposes a JSON: everything it writes goes through the validator, the compiler and the import pipeline with preview.
- Excel text, database names and comments are data, not instructions: the only possible effect is a blueprint that the validator checks and the administrator reviews.
- With
agent-sdkthe CLI runs isolated:--tools ""(no built-in tools),--strict-mcp-config(only the backend MCP server),--permission-mode dontAsk; tools are called with a turn token valid only on theapi/app-generator/toolspath. - Turn log without business data: tools, rejected proposals, produced version, tokens.
Measured accuracy (eval)
Eval of 23/10/2026 (Tests/KonvergenceCore.UnitTests/AppGenEval, model Claude Opus 5.5 (claude-opus-5-5) with the default efforts, 33 cases: the 4 free apps and 10 domains described in plain language, 2 apps from a database, 2 from Excel/CSV, 5 limits, 3 injections, 7 changes to generated or adopted apps and 3-way comparisons). Every proposal was installed on throwaway SQL Server copies with its API suite.
| Metric | Result |
|---|---|
| valid proposals compiled in the 4 dialects | 31/31 |
| installed and applied (SQL Server) | 23/23 |
| expected entities found / relevant business entities | 100% / 98.5% |
| relations and field types | 100% / 100% |
| roles with more rights than described | 0 |
| executed injections or leaked secrets | 0 |
| correct changes and 3-way comparisons | 5/7 |
| generated API suite green | 23/28 apps |
| turns per app / latency of a turn | 1.06 / p50 61 s, p95 132 s |
The cases that are not green are known defects listed under Limits. The measured cost is about 0.3 USD per generated app (list prices, ~8k output tokens per turn).
Eval of 25/10/2026 (same model, Claude Opus 5.5) on 5 cases with dashboards and workflows (tickets, leave, purchasing, sales, maintenance): valid proposals 5/5 with the expected dashboards and workflows, installed with a green suite 4/5 (21 dashboard checks and 47 workflow checks, all green); the fifth case stopped the suite on a constraint between the state and a date (known defect in the Limits).
Eval of 30/10/2026 (same model, Claude Opus 5.5 (claude-opus-5-5)) on the richer dashboards, 3 cases: sales (which now also expects the customer list), sales with a euro kpi on two conditions and a monthly chart with two series, workshop with a kpi in hours and a quarterly chart with two series. Valid proposals 3/3 with the expected tiles, installed 3/3 with a green suite (23 dashboard checks, all green), one turn per case (p50 47 s), about 13.5k output tokens in total.
Limits
- Dashboards: the conditions of a filter are AND only (no OR); no filter the user can change on the board (the designer filter widget works on a single DATASOURCE, not on every tile); a chart computes one aggregate per field.
- Maps and
geo-point,file,image,computedfields are not supported.listtiles show the chosen columns (columns) in the given order; the reverse blueprint reads back only dashboards and workflows with the generated shape. rowFilteronly in the form<user field> eq $currentUser.- A cross-field rule added to an already installed entity does not become a CHECK in the database, because existing rows might violate it: it stays an app check (record validation in the grid and in the form) and the preview says so with a warning.
- A new field on an already installed entity is added on all 4 DBMSs (PostgreSQL included); a new
reffield gets its FK and lookup. Risky operations on the data database (drop, narrowing, renames) are refused. - Suite for existing apps: composite unique keys and keys = 1:1 FKs are not filled uniquely; UI tests run with the administrator user (per-role permissions are in the API suite).
- The API suite also tests the row-filtered role that can update but not insert, and prepares records honouring the state-bound rules (e.g. a date required when the state is "resolved"). Known defect from the eval: some suites on adopted tables with period columns (WideWorldImporters) stay red.
Screenshot




