KittoX 4.0: un approccio radicale allo sviluppo di applicazioni web con Delphi 🚀

di Carlo Barazzetta — Ethea S.r.l.


KittoX logo

Perché usare KittoX?

Chi sviluppa applicazioni gestionali in Delphi conosce bene il dilemma: il web è diventato la piattaforma naturale per distribuire software aziendale, ma portare la ricchezza di una UI data-driven sul browser significa — nella stragrande maggioranza dei framework — imparare un secondo linguaggio, progettare e mantenere un'API JSON, integrare un framework JavaScript che consuma quei payload, e mantenere sincronizzate due basi di codice completamente separate.

KittoX risolve questo dilemma con una scelta radicale: il server non espone dati, genera direttamente interfaccia utente.


🏛️ Da ExtJS a HTMX: una rivoluzione silenziosa

Le versioni precedenti di Kitto (1, 2 e 3) erano basate su ExtJS, una libreria commerciale da ~1,5 MB che richiedeva una corrispondenza 1:1 tra ogni componente visuale lato client e una classe Delphi lato server. Ogni TKExtGridPanel, ogni TKExtFormPanel era il riflesso di un widget ExtJS. Il codice Delphi emetteva codice JavaScript e JSON per istanziare quei widget nel browser.

Era un'architettura funzionante, ma rigida:

KittoX 4.0 rompe completamente con questo modello. Il client è ora composto da:

Libreria Peso Ruolo
HTMX 2.0.4 14 KB Partial page update via attributi HTML
Alpine.js 3.14.8 16 KB Reattività locale minima (dropdown, toggle)
SVG Icons SVG inline 2122 icone Material Design, 5 stili
jQuery (slim) ~30 KB Compatibilità plugin legacy

Totale stack client: ~30 KB contro 1,5 MB di ExtJS. Ma il cambiamento non è solo quantitativo.


⚡ Il paradigma HTMX: il server genera informazioni, non dati

Questa è la scelta più radicale di KittoX, e vale la pena soffermarsi.

Nel modello di API JSON che si è imposto negli ultimi quindici anni il server espone endpoint REST che restituiscono dati strutturati in JSON. Il client — un'applicazione React, Angular, Vue — riceve quei dati grezzi e li trasforma in HTML, gestisce lo stato, si occupa del routing lato client, dell'autenticazione del token, degli errori di rete. Il server non sa nulla di come i dati verranno mostrati; il client non sa nulla del business logic.

Con HTMX il server fa qualcosa di diverso: risponde direttamente con frammenti HTML già renderizzati. Quando l'utente clicca “pagina successiva” in una griglia, HTMX invia una richiesta al server e il server risponde con il markup della nuova pagina di righe — non con un array JSON che il client dovrà iterare e trasformare. Il browser si limita a sostituire un <div> con il frammento ricevuto.

Flusso HTMX: Browser → KittoX Server

Non c'è un payload JSON intermedio. Non c'è serializzazione/deserializzazione. Non c'è gestione dello stato applicativo lato client. Il server conosce il contesto (sessione, permessi, lingua, database attivo) e genera HTML che già include quella conoscenza. L'utente vede sempre informazioni coerenti, non dati grezzi da interpretare.

🧠 REST non scompare ma è più “puro”. Le richieste sono HTTP, gli URL identificano risorse, il server resta stateless. Cambia solo il media-type della risposta: HTML al posto di JSON — è il principio HATEOAS descritto da Roy Fielding nel 2000. KittoX non elimina REST: collassa il doppio rendering (server → JSON → client → HTML) in un solo passaggio.

Questo approccio richiede zero JavaScript per il 99% delle funzionalità: paginazione, ordinamento, filtri, apertura form, submit, navigazione — tutto è gestito da attributi HTMX (hx-get, hx-post, hx-target, hx-swap) dichiarati nel markup generato dal server.

KittoX architecture

Nell'immagine lo schema dell'architettura di KittoX.


📋 Niente ORM, niente classi mappate: il database è il modello

In un'architettura tradizionale con ORM si scrivono classi Delphi che mappano le tabelle, si gestiscono le migration, si serializza il record object graph in JSON, si deserializza sul client. KittoX elimina tutto questo strato.

Il modello in KittoX è un file YAML che descrive direttamente la struttura del database, con tre differenze fondamentali rispetto a ciò che un database SQL esprime nativamente.

1. Campi calcolati come espressioni SQL

Un campo può essere il risultato di una qualsiasi espressione SQL, eseguita direttamente dal database senza alcun codice Delphi intermedio:

Party_Period: String(20)
  DisplayLabel: Period
  Expression: |
    case
      when %DB.CURRENT_DATE% - PARTY.PARTY_DATE < 0 then cast('Future' as varchar(10))
      when %DB.CURRENT_DATE% - PARTY.PARTY_DATE = 0 then cast('Today' as varchar(10))
      when %DB.CURRENT_DATE% - PARTY.PARTY_DATE between 2 and 7 then cast('Last Week' as varchar(10))
      else cast('Older' as varchar(10))
    end

Il campo Party_Period non esiste nella tabella: è calcolato sul server SQL ad ogni query, con la logica espressa direttamente in YAML. Niente OnCalcFields, niente classi intermedie, niente deserializzazione parziale.

2. Reference vs. DetailReference: ciò che le FK non dicono

Una foreign key SQL esprime solo un vincolo di integrità referenziale. Non dice nulla sulla semantica della relazione: questa FK è un semplice riferimento a una tabella di lookup, oppure è la chiave di una relazione master-detail che richiede un tab di editing separato?

KittoX distingue esplicitamente i due casi nel modello YAML:

# Il progetto "appartiene" a un cliente → Reference (lookup)
CUSTOMER: Reference(CUSTOMER) not null
  Fields:
    CUSTOMER_ID:

# Il progetto "contiene" fasi → DetailReference (master-detail)
DetailReferences:
  PHASE: PHASE

Questa distinzione guida automaticamente il rendering: un Reference genera un combo/lookup nel form; un DetailReference genera un tab con griglia CRUD all'interno del form di editing. Tutto automatico, senza scrivere una riga di codice Delphi.

3. Convention over configuration, niente boilerplate

KittoX applica il principio DRY a ogni livello. Se non si specifica un DisplayLabel per un campo nel modello, il framework lo sintetizza dal nome del campo. Se non lo si specifica nella vista, eredita quello del modello. Se non si specifica la larghezza di una colonna, viene calcolata dal tipo di dato. Se non si specifica un ordinamento, usa il DefaultSorting del modello.

Il risultato è che una vista tipica per una tabella di medie dimensioni si scrive in meno di 10 righe di YAML:

Type: Data
Controller: List
MainTable:
  Model: CUSTOMER
  DetailTables:
    Table:
      Model: PROJECT

Questa definizione produce automaticamente: griglia con tutte le colonne visibili, toolbar CRUD, ricerca full-text, paginazione (se il modello è IsLarge: True), tab master-detail per i progetti del cliente, form di editing con validazione, gestione della FK in sola lettura nel form detail.


🎨 Composizione delle View: YAML, non codice

Le View in KittoX sono combinazioni di Controller — componenti visuali configurabili tramite YAML. I controller di layout (BorderPanel, TabPanel, FlexPanel) si annidano liberamente; i controller di dati (List, Form, ChartPanel) si inseriscono nelle regioni.

Un layout tipico di una home page:

Controller: BorderPanel
  NorthView:
    Controller: ToolBar
      ...
  WestView:
    Controller: TreePanel
      ...
  CenterView:
    Controller: TabPanel
      ...

Non si scrive nemmeno un TForm, non si trascina un componente. La struttura dell'interfaccia è dichiarativa, leggibile, versionabile su git, modificabile senza ricompilare.

BorderPanelExample

Nell'immagine il layout dell'applicazione demo HelloKitto.

I controller disponibili coprono l'intera gamma delle necessità di un gestionale:

Categoria Controller
Layout BorderPanel, TabPanel, FlexPanel, TilePanel
Dati List, GroupingList, Form, Wizard, TemplateDataPanel
Navigazione TreePanel, ToolBar, HtmlPanel, StatusBar
Enterprise ChartPanel, CalendarPanel, GoogleMap, Dashboard

Edit Activity

Nell'immagine il controller List/Grid delle attività nella demo Taskitto. In primo piano la form di editing.


🔧 Il sistema a Macro: SQL, sessione e configurazione in un unico linguaggio

Le macro sono stringhe delimitate da % espanse a runtime in qualsiasi punto dei metadati YAML. Permettono di rendere dinamica qualsiasi parte della configurazione senza scrivere codice:

# Utente corrente nel titolo
DisplayLabel: Ordini di %Auth:UserName%

# Data corrente come DefaultValue
DefaultValue: %DATE%

# Chiave primaria auto-generata
DefaultValue: %COMPACT_GUID%

# Valore da Config.yaml
DefaultValue: %Config:App/DefaultCurrency%

# Espressione SQL dialect-agnostic
Expression: SELECT COUNT(*) FROM ORDERS WHERE %DB.CURRENT_DATE% - ORDER_DATE < 30

Le macro DB.* sono particolarmente potenti: si espandono nella funzione SQL corretta per il database attivo (current_date su PostgreSQL/Firebird, getdate() su SQL Server), permettendo di scrivere una sola espressione che funziona su tutti i database supportati.


🌍 Supporto multi-database e multi-lingua integrato

Multi-database

KittoX supporta nativamente più connessioni di database nella stessa applicazione. Ogni modello può essere instradato verso un database specifico:

# Config.yaml
Databases:
  Main: FireDAC_SQLServer
    ...
  Reporting: FireDAC_PostgreSQL
    ...

# In un Model.yaml
DatabaseRouter: Static
  DatabaseName: Reporting

Il routing è supportato a livello di modello, di vista e persino a livello di autenticatore — è possibile avere utenti su un database e dati su un altro. Database supportati: SQL Server, PostgreSQL, Firebird, Oracle (e qualsiasi altro tramite FireDAC).

Multi-lingua

KittoX integra GNU gettext (dxgettext) per la localizzazione. Le stringhe dell'interfaccia generata dal server — label, messaggi di errore, titoli — vengono automaticamente tradotte in base alla lingua della sessione corrente. L'utente può cambiare lingua dal login senza riavviare l'applicazione; ogni sessione mantiene la propria lingua indipendentemente.

Il sistema di macro %Auth:Environment% e %Auth:UserName% è già localizzato per default.


🖥️ GUI avanzata pronta all'uso

Uno dei vantaggi più concreti di KittoX è che le funzionalità GUI più richieste in un gestionale sono già implementate e richiedono solo configurazione YAML.

Liste e griglie

Il controller List offre out-of-the-box:

HelloKitto_Dolls

Nell'immagine la griglia con “gruppi” della demo HelloKitto.

Menu di navigazione

Tre stili di menu pronti all'uso, tutti configurabili in YAML:

TilePanel

Nell'immagine un menu “TilePanel” di una applicazione realizzata con KittoX.

Layout a template

Il controller TemplateDataPanel permette di definire layout HTML personalizzati per visualizzare dati in sola lettura, usando template con placeholder es.{Doll_Name}:

Controller: List
  TemplateFileName: DollsCard.html

Il template HTML definisce il layout per la griglia.

<div class="kx-card-body" style="width:300px;height:150px">
  <div class="kx-card-photo">
    <img src="{Picture}" alt="Doll Picture"
         onerror="this.onerror=null;this.outerHTML='<span class=kx-no-pic>No Doll Picture</span>'">
  </div>
  <div class="kx-card-info">
    <span class="kx-card-name">{Doll_Name}</span>
    <span class="kx-card-detail">{Date_Bought:date}</span>
    <span class="kx-card-detail">{Hair} hair</span>
    <span class="kx-card-detail">Size: {Dress_Size}</span>
  </div>
</div>

Il template yaml definisce il layout della form di editing, anche “multipagina”:

Row:
  Field: Doll_Name
    CharWidth: 20
  Field: Date_Bought
Row:
  Field: Mom
    CharWidth: 20
  Field: Mom_Phone
    CharWidth: 10
    DisplayLabel: _(Mom's Phone)
PageBreak: _(Characteristics)
Row:
  Field: Hair
  Field: Dress_Size
Row:
  Field: Aspect
    CharWidth: 16
    Lines: 14
  Field: Picture

Niente codice Delphi, niente JavaScript: un template HTML con placeholder e il controller fa il resto.

TasKitto Nell'immagine la lista in modalità “TemplateDataPanel” del catalogo “bambole” in HelloKitto e la form di editing con 2 pagine


📊 GUI Enterprise: grafici, calendari, mappe, dashboard

Per le applicazioni che richiedono visualizzazioni avanzate, la versione Enterprise include controller pronti all'uso:

Activity_Dashboard

Nell'immagine il layouyt (flex) del componente Dashboard nella demo Taskitto.

Tutti questi controller seguono lo stesso modello degli altri: si inseriscono in una vista con poche righe YAML, si alimentano con una query SQL, si configurano con proprietà YAML. Non si scrive JavaScript.


🔐 Strumenti enterprise: autenticazione e controllo accessi

JWT Authentication

KittoX include un authenticator JWT moderno (Auth: JWT) che:

Access Control via claim JWT

AccessControl: JWT legge le righe di permesso direttamente dal claim kx_acl nel token — zero query al database per ogni chiamata IsAccessGranted. Le stesse semantiche wildcard/regex dell'AccessControl: DB classico, ma con la velocità di una struttura in memoria.


🛠️ KIDEX: l'IDE visuale per KittoX

KIDEX (KittoX IDE Enterprise) è l'ambiente di sviluppo visuale per KittoX, che accelera le operazioni più ripetitive:

KIDEX è basato su attributi RTTI personalizzati (YamlNode, YamlContainer, YamlSubNode) che decorano le classi Delphi del framework: l'IDE scopre automaticamente le proprietà disponibili, i tipi, i valori ammessi — nessun file di template manuale da aggiornare a ogni release.

KIDEX

Nell'immagine l'ambiente di sviluppo integrato KIDEX.


🤖 MCPKittoX: KittoX parla con gli agenti AI

La novità più innovativa di KittoX 4.0 Enterprise è MCPKittoX, un server standalone (MCPKittoX.exe) che implementa il Model Context Protocol (MCP) e permette ad agenti AI come Claude Desktop, Claude Code, Codex e LM Studio di guidare lo sviluppo KittoX in modo conversazionale.

Cosa significa in pratica

Un agente AI con MCPKittoX configurato può, in una singola conversazione:

Sviluppatore: "Crea un'applicazione KittoX chiamata Gestionale sotto D:\Dev,
               con FireDAC e SQL Server Northwind, poi genera i modelli
               per tutte le tabelle."

→ MCPKittoX:
  1. Chiama project_create_app → scaffolding completo del progetto
     (con Auth: JWT/TextFile già configurato, app funzionante subito)
  2. Chiama models_create_from_db con dry_run=true → mostra l'albero
     delle azioni proposte (29 modelli, 177 campi, 13 reference)
  3. Con l'ok dello sviluppatore, dry_run=false → scrive i YAML.
     Output byte-identico al Model Wizard visuale di KIDEX.
  4. Il progetto compila al primo tentativo.

Sicurezza e sandbox

MCPKittoX è read-only per default. Le operazioni di scrittura richiedono --allow-update esplicito; le eliminazioni richiedono --allow-delete e seguono un pattern a due fasi (preview → conferma). Il flag --workspace=PATH crea una sandbox che impedisce qualsiasi accesso al filesystem fuori dalla radice specificata.

9 tool implementati (Fasi 1–3)

Scope Tool Descrizione
meta meta_version, meta_capabilities, meta_list_metadata_templates Info server, feature flags, template disponibili
project project_open, project_info, project_list_apps, project_close, project_create_app Gestione progetto completa
models models_create_from_db Reverse engineering modelli da database

La roadmap (Fase 4+) include generazione di View, Layouts, MainMenu, validatori, aggiornamento file di localizzazione, introspezione del database — tutto conversazionalmente, senza aprire RAD Studio.


🔌 Estensibilità: routing attribute-based

KittoX non è un sistema chiuso. Il routing HTTP è basato su attributi RTTI Delphi, ispirato a MARS/WiRL:

[TKXPath('/kx/view/{ViewName}')]
TKXMyHandler = class
public
  [TKXPath('/custom-data')]
  [TKXGET]
  procedure HandleCustomData(
    [TKXPathParam('ViewName')] const AViewName: string;
    [TKXContext] ADataView: TKDataView);
end;

initialization
  TKXResourceRegistry.Instance.RegisterResource(TKXMyHandler);

Un handler personalizzato si registra nell'initialization della propria unit: basta includerla nel progetto e il routing viene scoperto automaticamente via RTTI. Nessuna modifica al framework, nessuna registrazione manuale in file di configurazione centrali. È lo stesso meccanismo con cui sono implementati i moduli enterprise (Chart, Calendar, Map): includerli o escluderli dal progetto è sufficiente per attivare o disattivare le relative funzionalità.


📦 Strumenti di reportistica e export già pronti

Il framework include tool enterprise per le operazioni più comuni in un gestionale:

Ogni tool è un Controller YAML: si attiva aggiungendo poche righe alla definizione della vista, senza nessun codice Delphi.


🚀 Deploy flessibile: cinque modalità

KittoX non è legato a un solo modello di deploy:

Modalità Descrizione
Standalone Server Indy integrato, avvio diretto come VCL app o Windows Service
Desktop Embedded WebView2 dentro una finestra VCL — aspetto desktop nativo, zero browser chrome
Console Server headless, Docker-friendly
ISAPI (IIS) DLL nativa IIS, massima integrazione Windows Server
Apache Module Modulo Apache 2.4 nativo

Lo stesso codice sorgente, gli stessi metadati YAML, cinque .dpr di deployment — uno per modalità, generati automaticamente dal wizard.


📥 Come ottenere KittoX

KittoX è disponibile in due edizioni complementari, entrambe scaricabili e provabili senza alcun costo iniziale.

🆓 Edizione Open Source (Apache 2.0)

Il core di KittoX è interamente open source sotto licenza Apache 2.0, una delle licenze più permissive disponibili: utilizzo libero — anche commerciale e closed-source — senza royalty, senza obblighi di redistribuzione del codice. Include tutti i controller fondamentali (List, Form, Wizard, BorderPanel, TabPanel, TreePanel, TilePanel, TemplateDataPanel, GroupingList, HtmlPanel, StatusBar, ToolBar, FlexPanel), il routing attribute-based, l'autenticazione JWT, il supporto multi-database e tutte le tre applicazioni di esempio (HelloKitto, TasKitto, KEmployee).

Due modalità di installazione:

Setup automatico (consigliato): 👉 Scarica KittoXSetup.exe

L'installer copia i sorgenti, registra le path nell'IDE Delphi, installa l'IDE visuale KIDEX in modalità trial e configura tutto l'ambiente in pochi click.

Git clone (per chi vuole il sorgente):

git clone https://github.com/EtheaDev/KittoX.git

Il repository contiene i package Delphi pronti per le versioni 10.4, 11, 12 e 13, con script PowerShell per la build automatica di tutte le piattaforme (BuildAllPackagesD13.ps1 e simili).

💎 Edizione Enterprise — 90 giorni di trial

L'edizione Enterprise aggiunge i controller per visualizzazioni avanzate (ChartPanel, CalendarPanel, GoogleMap, Dashboard), gli strumenti di reportistica (ReportBuilderTool, ExportExcelTool con FlexCel, MergePDFTool), il Desktop Embedded Mode (WebView2) e — soprattutto — i due strumenti di produttività che cambiano il modo di lavorare con KittoX:

Il setup installa automaticamente una versione trial completamente funzionante per 90 giorni, sufficienti per valutare l'edizione Enterprise su un progetto reale, dalla prima riga di YAML al deploy in produzione.

Per richiedere la chiave di licenza trial dopo l'installazione, è sufficiente compilare il modulo di registrazione presente nell'IDE oppure contattare direttamente Ethea:

👉 ethea.it/supporto · ✉️ info@ethea.it

Allo scadere del trial, il framework KittoX (Core + moduli Enterprise compilati) continua a funzionare regolarmente: solo l'IDE KIDEX e MCPKittoX richiedono una licenza commerciale per proseguire l'uso.

📚 Documentazione completa

L'intera documentazione di KittoX è pubblicata online, costantemente aggiornata e ricercabile:

👉 ethea.it/docs/kittox/

Oltre 100 pagine che coprono ogni aspetto del framework: dalla guida introduttiva ai riferimenti dettagliati di ogni controller, dai pattern architetturali (master-detail, ACL stratificate, JWT) ai How-To pratici (campi calcolati, immagini come field, filtri condizionali, upload BLOB, multi-database). Ogni pagina include esempi YAML funzionanti tratti dalle applicazioni demo, così che ogni concetto sia immediatamente verificabile clonando il repository.

Le tre applicazioni di esempio — HelloKitto, TasKitto, KEmployee — sono progetti completi che mostrano pattern di uso reale: master-detail multi-livello, autenticazione DB / TextFile / custom, ACL a tre livelli, supporto multi-database (SQL Server / PostgreSQL / Firebird sulla stessa applicazione), localizzazione, dashboard, esportazioni.

🌐 Demo live: provale subito nel browser

Tutte e tre le applicazioni di esempio — insieme a KittoSCM, una vera applicazione multi-tenant in produzione — sono disponibili online e accessibili immediatamente da qualsiasi browser, senza scaricare o installare nulla. Ogni demo esegue esattamente il codice sorgente incluso nella distribuzione: navigando l'applicazione vedi il framework all'opera, e poi puoi aprire il YAML corrispondente nel repository per capire come è stato costruito.

Demo URL Descrizione
🎀 HelloKitto scm.ethea.it/hellokittox/ Showcase di partenza: griglie con grouping, card layout, master-detail, menu tile/tree, mobile mode
📋 TasKitto scm.ethea.it/taskittox/ Task tracker con progetti/fasi/attività, calendario, dashboard con grafici, ACL a tre livelli
👥 KEmployee scm.ethea.it/kemployeex/ Gestionale dipendenti su Firebird Employee.fdb, reference multi-campo, tema Neptune
🏆 KittoSCM scm.ethea.it/scm/ Applicazione reale in produzione: gestionale multi-tenant per ASD sportive italiane (~90 modelli, FatturaPA, dual-mode utenti/admin)

::: tip Credenziali demo Per HelloKitto, TasKitto e KEmployee usa utente: guest password: password. Per KittoSCM puoi accedere come genitore (BRZCRL68B12C523K / password) o come amministratore ASD (SYSDBA / password). :::

KittoSCM è particolarmente interessante: non è una demo costruita per mostrare il framework, ma un'applicazione vera in produzione distribuita a diverse associazioni sportive italiane dallo stesso codice base, con override Config.yaml per club. Gestisce iscrizioni, gruppi famigliari, quote e rate, visite mediche, tesseramenti, messaggistica interna, contabilità e fatturazione elettronica FatturaPA. È la dimostrazione concreta di quanto in profondità si possa spingere KittoX in scenari di business reali.

Per il dettaglio completo delle feature di ogni demo, vedi la pagina Live Demo della documentazione.


🏁 Conclusione

KittoX è una scelta deliberatamente radicale: anziché adattarsi alle convenzioni recenti del web (API JSON, SPA framework, ORM), ridisegna l'architettura attorno al punto di forza di Delphi — la capacità di costruire logica server-side robusta, connessa direttamente ai database relazionali — usando HTMX per portare REST nella sua forma più efficiente.

Il risultato è un framework dove:

Per i team Delphi che sviluppano applicazioni gestionali, KittoX offre qualcosa di raro: la possibilità di consegnare una web application completa e professionale investendo il proprio tempo sulla logica di business — non sull'infrastruttura.

🏢 KittoX in Ethea: framework di produzione, non vetrina

KittoX è il framework che Ethea S.r.l. utilizza per realizzare le proprie applicazioni enterprise. Ogni evoluzione del framework nasce dalle esigenze concrete di progetti reali in produzione — gestionali aziendali, sistemi di workflow, portali di reporting, applicazioni verticali.

Quando si sceglie KittoX, si adotta lo stesso strumento con cui Ethea consegna i propri progetti — con la garanzia di un team che lo conosce in profondità e che lo evolverà ancora a lungo.

Logo-Ethea

Se vuoi valutare KittoX per un tuo progetto, scarica il setup, prova l'edizione Enterprise per 90 giorni e — se vuoi confrontarti con noi su un caso d'uso concreto — siamo a disposizione. 🚀

Happy Kittoing!


Carlo Barazzetta — Ethea S.r.l. info@ethea.it · www.ethea.it · Documentazione KittoX KittoX 4.0 — Apache 2.0 (core) / AGPL-3.0 o Commerciale (enterprise) · Trial 90 giorni