Framework Overview

WUIC Framework is a metadata-driven platform for building business interfaces quickly and consistently.

What It Includes

• DataSource and DataRepeater for orchestrating data and rendering.
• Visual archetypes (list, map, scheduler, chart, carousel).
• Runtime designer for dashboards and dynamic templates.
• Workflow designer/runner for operational processes.
• RAG Chatbot for querying the codebase in natural language.
• Multi-DBMS: SQL Server, MySQL, PostgreSQL and Oracle via drop-in providers (dbms: mssql | mysql | postgresql | oracle).

First Steps — Starting the Dev Environment

The WUIC stack is composed of several services. Start them in the order below.

Prerequisites

> On Windows Server the database must be installed first. The one-liner pulls missing

> components through winget, which is not present on Windows Server: without an instance

> already reachable the installation stops with `No SQL Server instance reachable and winget is

> missing`. Install the engine before running the line - SQL Server must be 2019 or newer

> (Express is enough; 2022 or newer for the .bak tutorial), and a 2017 instance is not

> accepted. If the instance is not the default one, pass it with

> -SqlServer 'localhost\INSTANCENAME'. This applies to every engine, not just SQL Server.

1. Download the project template

On Windows one PowerShell line does all of it: it downloads the package, checks the .NET SDK 10

and Node.js 22 (installing what is missing), runs dotnet restore and npm install,

and installs the WUIC Assistant extension in VS Code.

Useful options on the same line: -Dbms mysql (or postgres, oracle) for an engine other

than SQL Server — the installer installs and configures it for you — and -WithTutorial to

download the sample database as well.

When it is done, the last screen is already your to-do list: open the workspace file

WuicTest.code-workspace in VS Code and press F5, which starts backend and frontend

together through the Fullstack: WuicTest + Chrome launcher (the launchers live in

.vscode/launch.json, next to the backend-only one). If you prefer the terminal, the

equivalent commands are further down this page.

The connection string is ready to use: at first start the wizard asks for nothing else. With

-Dbms mysql or -Dbms postgres that line changes accordingly and carries user and password

inside it, because the superuser password is generated by the installer; the same password

is saved in wuic-secrets.json, next to the installation, and that is the only place where it

stays written.

The manual path still works, on any operating system:

Start from the WuicTest-src-*.zip package (link in the Download section of the site).

Extract it to a working folder, e.g. C:\dev\WuicTest (files go directly at the root —

NOT inside a src/ subfolder). The package contains:

• WuicTest.csproj → host project with <PackageReference Include="WuicCore" Version="..." />
• wwwroot/ → Angular app whose package.json references wuic-framework-lib from the npm registry
• appsettings.json preconfigured in firstRun = "true" mode with __SET_*__ placeholders
• appsettings-samples/ → 6 ready templates (mssql/mysql, firstRun/post-firstRun, Development)

> No need to clone the framework repository: WuicCore ships as a NuGet package from

> nuget.org and wuic-framework-lib as an npm package from the npm registry. The framework

> source is only needed if you want to modify it — typically not your case.

> npm 10.9.x and packages older than 1.7.1: those packages carry no package-lock.json, and

> without a lock npm 10.9.x (the version Node 22 LTS installs) stops with

> Cannot read properties of null (reading 'edgesOut') while resolving peer dependencies.

> Download the lock published next to the release —

> https://wuic-framework.com/downloads/locks/<zip-name>.package-lock.json — drop it in wwwroot/

> and run npm install again. The -Src one-liner does it for you.

2. Database

You need a reachable engine instance. With the one-liner there is nothing to do: it

installs and configures the instance, and the connection string to paste into the wizard is the

last thing it prints. On the manual path the instance must already exist.

Connections in appsettings.json:

• MetaDataSQLConnection — metadata DB (menu, tables, columns, boards, users)
• DataSQLConnection — application data DB

If this is the first installation (AppSettings.firstRun = "true" in the template),

the scaffolding wizard on first startup creates the metadata schema and populates the data DB.

See the Initial Scaffolding page for the guided flow.

#### What the first-run wizard asks for

On the first start the application does not show the login form but the **Initial project

setup** page. You fill it in once: when it finishes firstRun flips to false and the page

never comes back.

• Setup mode — two entries: Existing database, which registers a database of your own,

and Tutorial WideWorldImporters, which installs the sample database. The second one only

appears when the package ships the tutorial (tutorialAvailable): in packages without it the

dropdown is not rendered at all and the mode is "Existing database".

• DBMS — the engine. Changing it rewrites the connection string below in the shape of the

chosen provider.

• DataSQLConnection — the string to the data database, and the field everything else

depends on: until you press Test connection and load databases the database list stays

disabled. The test validates the credentials, lists the databases on the server and, on SQL

Server, fixes the certificate parameters for you

(Encrypt=False;TrustServerCertificate=True), telling you it did. Integrated Security

only works on SQL Server: the other engines need a user and a password.

• Data database and Metadata database name — the first is picked from the list the test

loaded (in tutorial mode it is a free-text field, WideWorldImporters by default); the

second is the name of the metadata database to create (metadataDB by default,

MetadataCRM in tutorial mode). If that database already exists, the wizard asks before

recreating it.

• Scaffold the tables automatically (only in "Existing database") — fills

_metadati__tabelle / _metadati__colonne from every table of the chosen database. It is

what lengthens provisioning the most on databases with many tables.

• Initial admin user — username (admin by default), password (at least 4 characters) and

language. There is no default password: the one you type here is the only one that will let

you in at the first login. The language you pick is applied to the admin user and to this

page itself. If the username matches a user already present in the metadata DB, the chosen

password and language are applied to that user. The wizard also creates the wuic_assistant

user for the WUIC Assistant, with a generated password: see RAG Chatbot.

• RAG Chatbot — only the Anthropic key, and it is optional. Nothing to install: see step 5.

Once you press Confirm and create the metadata database provisioning runs on its own, with

a progress bar and the number of batches processed. How long it takes, measured on the test

installations: 30 s - 2 min in tutorial mode, 1-4 min on an existing database with

automatic scaffolding enabled. When it ends, the page gives way to the login form.

3. Backend (.NET)

From the root of the extracted folder (e.g. C:\dev\WuicTest):

The backend exposes APIs on http://localhost:5000.

4. Frontend (Angular)

In a second shell, from the wwwroot/ subfolder:

The frontend is available on http://localhost:4200.

The credentials are those of the admin user you chose in the first-run wizard: the username

is admin unless you changed it, and the password is the one you typed (there is no default

password).

5. RAG Chatbot (optional)

The RAG Chatbot (Administration > RAG Chat) runs inside the .NET backend:

the retrieval engine (rag-engine/WuicRagEngine.dll, in-process ONNX Runtime)

is loaded by the backend when AppSettings.rag-use-dotnet-engine is "true"

(the default in release packages). **No Python, no venv, no separate server

to start.**

The first time the chatbot is opened (or at the end of the first run) the

backend downloads by itself the ONNX models (bge-m3 + reranker), tokenizer

and index (~4.5 GB) from rag-engine-models-url (default

https://wuic-framework.com/rag-models) into rag-engine/artifacts/. An

internet connection is needed only once; the download runs in the background

(1-5 min) and an in-app notification is sent when it starts and when it ends.

Meanwhile the component shows the RAG offline status and the rest of the

application works normally.

Relevant AppSettings keys (all with ready defaults):

• rag-use-dotnet-engine = true — enables the .NET engine (false = Python fallback, see below)
• rag-engine-device = auto — auto | cuda | cpu: with an NVIDIA GPU (CUDA 12.x + cuDNN 9) ~1 s/query, on CPU ~15-25 s/query
• rag-engine-profile = release — release = framework sources as signatures only; internal = full index
• rag-engine-models-url — download source on first start
• rag-engine-cuda-path = (empty) — folder of the CUDA/cuDNN DLLs when they are not installed system-wide

For LLM chat set rag-llm-provider + rag-llm-api-key (Claude via Anthropic,

or a local model via Ollama with rag-llm-base-url). Without a provider only

the retrieval mode (snippet search) works. Key details on the AppSettings

page.

> The legacy Python stack (scripts/rag-setup.ps1 + rag_server.py on

> 127.0.0.1:8765) is only usable as a fallback with

> rag-use-dotnet-engine = "false" and is not shipped in release packages.

Services Summary

Quick Start — First Component

1. Configure the AsmxProxy endpoint.

2. Define route metadata and columns.

3. Mount wuic-data-source + wuic-data-repeater.

The first lists show 20 records: that is Trial mode

A fresh install runs without a license, that is, in Trial mode, and in that mode

every query is capped at 20 records. It is neither a bug nor a database limit: a list

that reads "20 of 20" on a table with thousands of rows is simply running unlicensed.

How to confirm it in a second:

licenseValid: false confirms the Trial, and licenseReason says why

(invalid_signature, license_expired, machine_fingerprint_not_authorized, ...).

How to get out of it: paste the license from Administration > AppSettings Editor, Licensing

tab, and it takes effect immediately - no backend restart needed. The details, including the

limits the Trial imposes beyond the record count, are in the Licensing page.