Inizia in 10 minuti

Questa pagina sono i tuoi primi dieci minuti dentro Archestack: accedi a un trial nuovo, impari a riconoscere ogni pannello dell'app, fai la tua prima modifica e impari le scorciatoie da tastiera che trasformano l'interfaccia da "passabile" a "veloce". Alla fine saprai abbastanza da seguire qualsiasi altra guida senza perderti.

Non hai ancora un trial? Apri archestack.eu e fai clic su Try it live - 7-day trial. Accedi con Google. Il tuo ambiente privato sarà pronto in circa 30 secondi e arriverai automaticamente sulla sua dashboard. Salva l'URL nei segnalibri, è unico per il tuo trial.

1. Accedi al tuo trial

Ogni trial riceve un URL univoco nella forma https://<slug>.trial.archestack.eu. Il banner del trial in cima a ogni schermata mostra quanti giorni mancano prima che l'ambiente venga distrutto. La gravità cresce man mano che ti avvicini alla scadenza (info -> warning -> error), così con un'occhiata sai se hai settimane o ore davanti.

L'app si apre sulla Home dashboard, volutamente vuota finché non costruisci qualcosa. Non preoccuparti, è proprio così che dev'essere. La prima volta, gli unici segnali che sei "dentro" sono la sidebar che compare a sinistra e il tuo nome in alto a destra.

Cosa cambia in modalità trial

Alcune funzionalità sono disabilitate nell'ambiente trial per proteggere l'infrastruttura condivisa. Appaiono in grigio (o restituiscono 403 se provi a chiamarle direttamente):

• Database Backups - disabilitati per prevenire abusi del disco.
• Rendering PDF - sia il pannello di anteprima dell'editor sia l'endpoint pubblico di generazione restituiscono 403; l'editor del template funziona comunque per la stesura (data script, HTML, settings), ma non vedrai un PDF renderizzato all'interno di un trial.

Tutto il resto funziona normalmente. Quando sei pronto a usare le funzionalità bloccate, contatta il team tramite il pulsante Upgrade del banner del trial.

2. Il layout, in un solo paragrafo

A sinistra, la sidebar inizia con un pulsante Quick Search (oppure premi Ctrl/Cmd+K) che apre la Command Palette, più una voce Home, e poi si apre in una sezione ADMINISTRATION divisa in EDITOR (dove passerai la maggior parte del tempo: Business Entities, Page Editor, Business Events, Script Modules, ecc.) e SYSTEM (strumenti di amministrazione: Database Deployments, Schema Designer, User Management, Branding, Backups). L'icona della campanella (in alto a sinistra, accanto al logo Archestack) mostra gli Event Log non letti con errori. In fondo alla sidebar trovi il toggle del tema (sole/luna), il menu del profilo, un toggle per la Desktop mode e un pulsante per chiudere la sidebar. Una volta pubblicata una pagina, compare sotto una sua sezione Modules sopra ADMINISTRATION.

Un giro più approfondito

• Sidebar - gruppo EDITOR. Business Entities, Object Browser, Third Party, Business Events, Script Modules, Frontend Templates, PDF Templates, Page Editor, Scheduled Events, Event Logs, Packages, Build with AI. La procedura guidata Build with AI compone un prompt per un LLM esterno (Claude, ChatGPT, Gemini) e applica il piano JSON che riceve in risposta, vedi "AI Builder" nella pagina di riferimento.
• Sidebar - gruppo SYSTEM. Database Deployments, Schema Designer, User Management, Translations, Business Units, Database Backups, Branding. Si usano meno spesso, ma sono essenziali quando ti servono.
• Modules (sopra ADMINISTRATION). Vuoto finché non pubblichi la tua prima pagina. Le pagine pubblicate stanno qui raggruppate per categoria, ed è da qui che gli utenti finali ci arrivano.
• Stat card della dashboard. Tables / Business Entities / Pages / Event Triggers / Scripts / Scheduled: ogni riquadro è cliccabile e ti porta alla relativa pagina di amministrazione.
• Pannello Quick Actions (lato destro della dashboard). Scorciatoie con un solo clic: New Page, New Entity, New Trigger, New Script, Build with AI, Schema Designer.
• Tab in cima. La maggior parte degli strumenti dell'editor si apre come tab nel pannello principale, puoi averne diverse aperte contemporaneamente. Fai clic su una tab per passare; chiudi con la x. Fai clic su + per aprire una nuova tab. Lo stato delle tab è memorizzato nell'URL, così un refresh mantiene quelle che hai aperte.
• Icona campanella (in alto a sinistra, accanto al logo). Notifiche di errore da Business Events, Script Modules e Scheduled Events. In tempo reale via SignalR, senza bisogno di ricaricare.
• Controlli in fondo alla sidebar. Toggle del tema (sole/luna: l'admin parte in scuro, questo sito Learn parte in chiaro, si commutano in modo indipendente), avatar del profilo (lingua + sign out), switch Desktop mode e collapse della sidebar.

Desktop mode

Sugli schermi larghi puoi premere Ctrl/Cmd+Shift+D per passare alla Desktop mode, un'interfaccia a finestre in cui ogni strumento si apre come una finestra trascinabile con una dock in basso. È la stessa app, solo con un layout diverso. Usa quella che ti viene più naturale; la documentazione fa riferimento al layout con sidebar perché è il default.

3. Fai la tua prima modifica in 5 minuti

Preferisci un tour guidato? La dashboard ha un pulsante Start guided setup nell'angolo in alto a destra. Apre un pannello che ti accompagna attraverso i sei blocchi fondamentali (tabelle -> entities -> pagine -> events -> scripts -> PDF), evidenzia il prossimo passo, e può precaricare un mini CRM (tabelle Customer / Contact / Note) così hai qualcosa con cui sperimentare. Il walkthrough qui sotto copre lo stesso percorso a mano, scegli quello che preferisci.

Il modo più veloce per sentirti produttivo è progettare una tabella semplice, farne il deploy e vederne i dati. Creiamo una tabella "note".

Progetta la tabella

1. Apri Schema Designer dalla sezione admin della sidebar (route: /schema-designer).
2. Nella toolbar in alto, fai clic sul pulsante icona etichettato Add Table.
3. Si apre un dialog intitolato Create New Table. Il campo "Table name" ti suggerisce la convenzione: minuscolo con underscore. Digita note. Fai clic su Create.
4. La nuova tabella compare sul canvas e il pannello laterale destro si apre con tre tab: Columns, Indexes, Relations.
5. Sei sulla tab Columns. Il sistema ha già aggiunto una colonna id (SERIAL primary key, bloccata). In fondo alla lista delle colonne c'è un box con bordo tratteggiato "Add column". Aggiungi altre tre colonne, una alla volta:
   • title - tipo VARCHAR, lunghezza 500, NULL disattivato (obbligatoria).
   • body - tipo TEXT, NULL attivato (opzionale).
   • created_at - tipo TIMESTAMPTZ, default now().
   Per ciascuna: digita il nome nel campo del nome colonna, scegli il tipo dal dropdown Type, fai clic su Add Column. Poi fai clic sulla nuova colonna per espanderla e regola i toggle (PK / NULL / UQ) e i campi Length / Default secondo necessità.
6. Lo schema si salva automaticamente, guarda l'indicatore in basso a sinistra passare da "Auto saving..." a "Saved".

Archestack aggiunge quattro colonne di audit, created_at, updated_at, created_by, updated_by, a ogni tabella automaticamente e le marca a ogni insert e update. Il created_at qui sopra è quindi opzionale (lo aggiungiamo per corrispondere allo screenshot); non devi mai creare o mantenere quelle quattro a mano.

Fai il deploy

1. Nella toolbar di Schema Designer, fai clic sul pulsante Deploy (icona razzo, verde). Vieni portato su /database-deployments/configure/new.
2. Atterri sulla tab Configuration. I pannelli degli script pre e post deployment sono vuoti (default). Passa alla tab Generated SQL per vedere la migration prodotta dalla piattaforma, dovrebbe essere un CREATE TABLE "note" (...).
3. Se l'SQL sembra corretto, fai clic sul pulsante Deploy in alto a destra. Lo stato si aggiorna in tempo reale; in caso di successo la riga del deployment in Database Deployments -> Overview mostra "Succeeded".

Aggiungi qualche dato

Per dare un'occhiata alla tua nuova tabella, apri Object Browser, scegli note dalla lista delle tabelle e fai clic su Add row. Digita un titolo e un body, salva. Hai appena creato il tuo primo dato.

Se qualcosa non torna

• La tabella non compare in Object Browser? Controlla Database Deployments: se il deployment non è andato a buon fine, la tabella non esiste. Quasi sempre i fallimenti sono conflitti di nome o combinazioni tipo/lunghezza non valide. La colonna di stato della riga del deployment ti dice qual è il motivo.
• Non vedi la tab Columns in Schema Designer? Probabilmente non hai selezionato una tabella, fai clic su un nodo tabella nel canvas. Il pannello destro compare solo quando qualcosa è selezionato.
• Il pulsante Deploy nella toolbar di Schema Designer è grigio? Di solito significa che non ci sono modifiche in attesa. Controlla l'indicatore di auto-save: se mostra "Saved" e non hai fatto modifiche dall'ultimo deployment, non c'è nulla da deployare.

4. Mettila dentro una vera pagina

Object Browser è una vista da power user, gli utenti finali vogliono un'interfaccia più amichevole. Diamogliela:

1. Apri Business Entities e fai clic su Create. Si apre un editor a tutta pagina. Imposta Entity Name su note, scegli Master Table = note, scegli Label Column = title. Salva. La tab Visual mostra le colonne auto-generate, puoi lasciarle così.
2. Apri Page Editor (route: /pages) e fai clic su Create. Compila Page Name = Notes, Page Route = /notes, Business Entity = note. Il page builder genera in automatico un layout sensato basato sulle colonne della BE.
3. Sposta lo Switch Published nell'header in alto su ON. La pagina compare sotto Published Pages nella sidebar. Fai clic, hai un'app di inserimento dati funzionante con ricerca, filtri e modifica.

Questo è l'intero loop: Schema -> Deploy -> Business Entity -> Page -> Publish. Ogni funzionalità di Archestack o si basa su questo loop o lo estende (gli events scattano quando i dati cambiano, gli script girano su pianificazione, i packages impacchettano l'output del loop per la promozione).

5. Scorciatoie da tastiera che ti rendono veloce

L'interfaccia di Archestack è mouse-friendly ma la maggior parte degli utenti esperti vive sulla tastiera. La lista qui sotto copre le scorciatoie che ripagano da subito.

Globali

• Ctrl/Cmd + K - apre la Command Palette. Cerca qualsiasi pagina, azione o Business Entity per nome. Il modo più veloce per navigare.
• Ctrl/Cmd + Shift + D - alterna la Desktop mode (UI a finestre ↔ UI con sidebar).
• Esc - chiude il dialog / popover più in primo piano.

In qualsiasi griglia di lista

• ↑ / ↓ - sposta la selezione di riga.
• Enter - apre la riga selezionata.
• Ctrl/Cmd + F - sposta il focus sulla casella di ricerca.

Negli editor di codice (script, data script PDF, frontend template)

• Ctrl/Cmd + Space - mostra i suggerimenti IntelliSense. Nota che Db, Modules, Entity, OldEntity e Log sono gli unici globali, l'autocomplete su questi funziona dentro qualsiasi script.
• Tab - accetta il suggerimento evidenziato. (L'accept-on-commit-character è disabilitato di proposito per evitare inserimenti accidentali quando volevi digitare una virgola o una parentesi.)
• Ctrl/Cmd + S - salva.

6. La Command Palette merita una sezione a sé

Ctrl/Cmd + K apre un overlay di ricerca fuzzy che ti permette di saltare ovunque nell'app digitando due o tre caratteri. Cerca:

• Pagine (sia gli strumenti admin sia le tue pagine pubblicate).
• Business Entities per nome.
• Azioni come "create new BE", "open Branding", "deploy schema".
• Elementi recenti che hai aperto, li ritrova con un solo tasto.

La Command Palette si apre con il focus sulla casella di ricerca, così puoi iniziare a digitare subito. Le frecce su/giù navigano, Enter seleziona, Esc chiude. Dopo qualche ora di utilizzo ti ritroverai a usarla per navigare più della sidebar.

7. Dove andare dopo

• Concetti chiave - leggilo se vuoi un modello mentale prima di cliccare qualunque altra cosa. Copre Business Entities, Pages, Events, Scripts e l'API Db chiamabile dagli script.
• Crea la tua prima app - un walkthrough più lungo e strutturato che si conclude con un mini-CRM multi-pagina (companies / contacts / deals) cablato con events di auto-stamping e uno script di ricalcolo.
• Genera fatture in PDF - si basa sui dati della prima app per aggiungere un template di fattura stampabile.
• Reference - voci focalizzate per ogni strumento in cui puoi pescare quando hai una domanda specifica.

Prime domande comuni

"Posso annullare un deployment?"

Non direttamente, non c'è un pulsante Undo. Il modo pulito di recuperare è applicare un deployment correttivo (eliminare una colonna che hai appena aggiunto, ecc.) oppure ripristinare da un backup. Su un ambiente a pagamento, fai un backup prima di modifiche rischiose. Su un trial, il recupero più semplice è avviare un nuovo trial.

"Posso avere più pagine sulla stessa BE?"

Sì, quante vuoi. Route diverse, layout diversi, scelte di colonne diverse. Pattern comune: una pagina lista semplice in /customers per tutti e una più dettagliata in /customers/admin per gli utenti di back-office (controllata da una Business Unit o da un ruolo).

"Dove modifico le etichette dei campi e le intestazioni delle colonne?"

In due posti, a seconda di cosa vuoi cambiare. L'etichetta che compare nella pagina (es. "Nome azienda" invece di "Nome") viene dalla configurazione delle colonne della Business Entity. L'etichetta che compare a livello di sistema per una chiave di traduzione (es. stringhe UI come "Save", "Cancel") sta in Translations.

"La mia pagina è vuota. Dove sono i miei dati?"

Tre soliti sospetti, in ordine di probabilità:

• Business Unit attiva sbagliata, controlla lo switcher BU nella barra in alto.
• La Business Entity ha un filtro di default che ti nasconde i dati, apri la BE e controlla.
• Hai aggiunto righe in Object Browser a una tabella diversa da quella che pensi (guarda il nome della tabella nel breadcrumb).

"Come ottengo l'email dell'utente corrente in uno script o trigger?"

Oggi non si può. Gli script hanno solo Entity, OldEntity, Log, Db e Modules, non c'è un globale User. Le template expression ({{ ... }}) analogamente non hanno un token {{ user.email }}. Se ti serve l'identità utente in una regola, catturala dal front end e passala sul record al momento dell'insert, poi leggila da lì.

"Posso eseguire Archestack in locale sulla mia macchina?"

Sì, c'è un docker-compose.yml nel repo che tira su un ambiente autocontenuto con PostgreSQL + Keycloak + API + Web. È documentato per gli ingegneri che vogliono sviluppare la piattaforma stessa. Per una valutazione, l'ambiente trial è molto più veloce da far partire.

"Come estendo la piattaforma con codice custom?"

Due punti di estensione coprono quasi tutto: Script Modules per la logica backend (C# compilato a runtime) e Frontend Templates per frammenti UI custom (TSX). Per cambiamenti più profondi, controller custom, nuove tabelle di cui la piattaforma stessa ha bisogno: lì siamo in territorio fork-and-build, fuori scope per questo sito.