Documento tecnico · web app multitenant per studi notarili

Preventivo tecnico

Architettura, modello dati, requisiti funzionali e non funzionali, piano di lavoro ed esclusioni per una piattaforma multitenant destinata alla vendita agli studi notarili. Ogni voce è numerata e verificabile in collaudo.

ModelloSaaS multitenant
Durata sviluppo6 settimane · 3 sprint
OpzioniA partnership · B chiavi in mano
ConsegnaCodice + IP + documentazione
01

Perimetro funzionale

Requisiti funzionali del sistema. La colonna Sprint indica in quale sprint il requisito è consegnato e collaudabile.

IDRequisitoDescrizione tecnicaSprint
RF-01Tenant per studioOgni studio notarile è un tenant isolato: dati, utenti e documenti separati a livello di schema applicativo. Nessuna query può restituire record di un tenant diverso dal contesto di sessione.S1
RF-02Autenticazione e ruoliLogin email/password con hash Argon2id, sessioni firmate, recupero password via token a scadenza. Ruoli: owner, notaio, segreteria.S1
RF-03Anagrafica studioRagione sociale, sede, P.IVA/CF, contatti, logo. I dati compaiono su ogni pratica e su ogni documento generato.S1
RF-04Pratica da preventivo accettatoCreazione pratica con: tipo atto, parti coinvolte (acquirente, venditore, agenzie), importi, data prevista, note. Genera un identificativo pratica univoco leggibile.S1
RF-05Sezione condivisa con tokenPer ogni parte viene generato un link con token opaco non indovinabile, scadenza configurabile e permessi limitati al ruolo della parte. Accesso senza registrazione.S2
RF-06Checklist documentale per ruoloSet di documenti richiesti differenziato per acquirente, venditore e agenzia. Stato per singolo documento: mancante, caricato, rifiutato, accettato.S2
RF-07Upload documentiUpload multiplo con limite di dimensione e tipi ammessi (PDF, JPG, PNG, DOCX). Storage su object storage con URL firmate; metadati in database. Anteprima per i formati supportati.S2
RF-08Controllo coerenza datiMotore di regole che incrocia i dati estratti dai documenti e i campi della pratica: date, importi, intestatari, dati catastali. Produce una lista di anomalie con gravità (bloccante, avviso).S2
RF-09Solleciti automaticiJob schedulato che rileva documenti mancanti oltre soglia e invia promemoria alla parte interessata con link diretto. Frequenza e soglia configurabili per studio.S2
RF-10Dashboard praticaVista per studio con stato di ogni pratica: percentuale completamento documentale, anomalie aperte, giorni di fermo, parti in attesa.S2
RF-11Compilazione atto da datiTemplate di atto con segnaposto risolti dai dati della pratica e dai documenti validati. Merge con anteprima delle incongruenze residue prima della generazione.S3
RF-12Export documentoGenerazione del documento finale nel formato concordato (PDF e/o DOCX), archiviazione nella pratica, download tracciato a log.S3
RF-13Archivio e ricercaPratiche concluse consultabili e filtrabili per parti, data, tipo atto, stato. Ricerca full-text sui metadati.S3
RF-14Log attivitàRegistro immutabile delle operazioni rilevanti: accesso ai link, upload, download, modifica dati, generazione atto. Con utente o token, timestamp, IP.S3
02

Architettura

Stack e scelte strutturali. Le alternative sono indicate dove la decisione ha un impatto economico o di tempi.

Applicazione

Monolite modulare in TypeScript, con rendering server-side e API interne tipizzate. Un solo deployable, moduli separati per dominio (pratiche, documenti, atti, amministrazione): più semplice da consegnare e da mantenere rispetto a microservizi, che su questo perimetro aggiungerebbero solo complessità operativa.

TypeScript · SSR · API interne

Persistenza

PostgreSQL gestito, con isolamento per tenant tramite tenant_id obbligatorio e policy a livello di applicazione, più schema dedicato per la parte documentale. Scelta preferita a un database serverless con limiti di concorrenza, perché qui le transazioni contano.

PostgreSQL · ORM tipizzato · migrazioni versionate

Storage documenti

Object storage compatibile S3 con bucket privato, accesso solo tramite URL firmate a scadenza breve. I file non sono mai pubblici. Naming per tenant e pratica, checksum SHA-256 per integrità e deduplica.

S3-compatible · URL firmate · checksum

Job asincroni

Coda per elaborazioni non bloccanti: parsing documenti, controllo coerenza, generazione PDF, invio solleciti. Le operazioni lunghe non stanno nella richiesta HTTP, così il caricamento resta immediato anche con file pesanti.

Queue · retry con backoff · dead letter

Estrazione dati dai documenti

Parsing deterministico per i PDF testuali (regex e layout), OCR per le scansioni, modello linguistico solo come fallback per i campi non strutturati. Ogni dato estratto resta modificabile a mano: l'automazione propone, l'umano conferma.

PDF parse · OCR · LLM fallback

Autorizzazione dei link

Token opachi a 256 bit, hashati a database, con permessi per ruolo della parte, scadenza e revoca immediata dal pannello dello studio. Ogni accesso è loggato. Un link non dà mai accesso a pratiche diverse da quella per cui è stato emesso.

Token opachi · revoca · scope per pratica
03

Modello dati

Entità principali e relazioni. Le entità di supporto (log, token, allegati) sono omesse per leggibilità.

EntitàCampi chiaveRelazioni
tenantid, ragione_sociale, sede, piva, logo, config_json1 → n utenti, pratiche
userid, tenant_id, email, password_hash, ruolo, staton → 1 tenant
praticaid, tenant_id, codice, tipo_atto, stato, data_prevista, importi_jsonn → 1 tenant · 1 → n parti, documenti, atti
parteid, pratica_id, ruolo (acquirente/venditore/agenzia), anagrafica_json, contattin → 1 pratica · 1 → 1 token
documentoid, pratica_id, parte_id, tipo, storage_key, checksum, stato, dati_estratti_jsonn → 1 pratica · n → 1 parte
checklist_itemid, pratica_id, ruolo_parte, tipo_documento, obbligatorion → 1 pratica
anomaliaid, pratica_id, regola_id, gravità, campo, atteso, rilevato, staton → 1 pratica
attoid, pratica_id, template_id, versione, storage_key, generato_da, generato_iln → 1 pratica
token_accessoid, parte_id, hash_token, scope, scadenza, revocato_iln → 1 parte
audit_logid, tenant_id, attore, azione, entità, entità_id, ip, timestampappend-only
Vincolo di isolamento. Ogni tabella applicativa porta tenant_id non nullo. Il livello di accesso dati applica il filtro dal contesto di sessione: non esiste codice applicativo che possa leggere senza tenant. È una scelta strutturale, non una convenzione.
04

Flussi principali

Sequenza tecnica delle due operazioni centrali del sistema.

A · Condivisione e raccolta documenti

// 1. Il notaio crea la pratica e invita le parti
POST /api/pratiche/{id}/parti        → parte + checklist_item generati
POST /api/pratiche/{id}/inviti       → per ogni parte: token_accesso (256 bit)
                                     → restituisce URL firmato + testo pronto per WhatsApp

// 2. La parte apre il link: nessuna registrazione
GET  /p/{token}                      → valida hash, scadenza, scope
                                     → sessione limitata alla singola pratica

// 3. Upload: file diretto su storage, metadati su DB
POST /api/upload/presign             → URL firmata (PUT, scadenza 15 min)
PUT  {storage_url}                   → file su bucket privato
POST /api/pratiche/{id}/documenti    → verifica checksum, accoda parsing
                                     → job: estrazione dati + aggiornamento checklist

// 4. Job pianificato: solleciti
CRON /jobs/solleciti                 → documenti mancanti oltre soglia
                                     → notifica con link riutilizzabile

B · Controllo coerenza e generazione atto

// 1. Il motore di regole gira sui dati disponibili
POST /api/pratiche/{id}/coerenza     → regole: date, importi, intestatari, catastali
                                     → anomalie{gravità: bloccante|avviso, campo, atteso, rilevato}

// 2. Il notaio rivede e conferma i dati estratti
PATCH /api/pratiche/{id}/dati        → ogni campo è editabile: l'estrazione propone
                                     → le anomalie bloccanti vanno chiuse prima dell'atto

// 3. Generazione documento dal template
POST /api/pratiche/{id}/atto         → merge segnaposto ← dati confermati
                                     → job: render PDF/DOCX
                                     → tracking giallo su campi non risolti

// 4. Export e archiviazione
GET  /api/atti/{id}/download         → URL firmata + voce in audit_log
05

Requisiti non funzionali

Criteri misurabili. Sono quelli che finiscono nel collaudo, non quelli che si scoprono dopo.

IDAmbitoRequisito
RNF-01SicurezzaPassword con Argon2id, HTTPS obbligatorio, header di sicurezza (CSP, HSTS, X-Frame-Options), rate limit su login e sugli endpoint pubblici dei link.
RNF-02IsolamentoNessuna query applicativa senza filtro tenant. Test automatico che tenta accesso cross-tenant su ogni endpoint e deve fallire.
RNF-03DocumentiBucket privato, URL firmate con scadenza ≤ 15 minuti, checksum verificato in upload, tipi MIME e dimensione validati lato server.
RNF-04PrestazioniApertura di un link con checklist: risposta server < 800 ms al 95° percentile. Upload reso immediato con elaborazione asincrona.
RNF-05BackupBackup giornaliero del database con retention a 30 giorni e ripristino provato in collaudo, non solo configurato. Documenti su storage versionato.
RNF-06TracciabilitàLog append-only di accessi, upload, download, modifiche e generazioni. Conservazione minima 24 mesi.
RNF-07GDPRBase giuridica e informativa per dati di parti e documenti di identità, tempi di conservazione configurabili per studio, cancellazione tracciata a fine retention.
RNF-08CompatibilitàUltime due versioni di Chrome, Safari, Firefox ed Edge su desktop; link condivisi utilizzabili da mobile senza installazione.
RNF-09AccessibilitàForm pubblici delle parti conformi WCAG 2.1 livello AA su contrasto, focus e navigazione da tastiera.
RNF-10ManutenibilitàMigrazioni versionate, ambiente di test separato, test end-to-end sui flussi critici, documentazione tecnica consegnata.
06

Piano di lavoro

Tre sprint da due settimane. Ogni sprint chiude con una demo e un blocco di requisiti collaudabili.

Sprint 1Fondamenta, tenant e praticheSettimane 1–2

Base dati, isolamento, autenticazione e creazione pratica. Al termine si può accedere, creare uno studio e inserire un preventivo accettato.

RF-01
Isolamento multitenant — schema, policy applicative, test di accesso cross-tenant.
RF-02
Autenticazione e ruoli — registrazione studio, login, recupero password, tre ruoli.
RF-03
Anagrafica studio — dati, logo, configurazioni iniziali.
RF-04
Pratica da preventivo — form completo, validazione, codice pratica.
INF
Infrastruttura — ambienti test/produzione, migrazioni, backup giornaliero, monitoraggio errori.
Demo 1: creazione studio, login, inserimento pratica con parti e importi. Verifica dell'isolamento tra due tenant.
Sprint 2Condivisione, upload e controllo coerenzaSettimane 3–4

Il flusso operativo completo lato parti. Al termine un'agenzia può caricare i documenti da link e il notaio vede cosa manca e cosa non torna.

RF-05
Link con token — generazione, scadenza, revoca, permessi per ruolo della parte.
RF-06
Checklist per ruolo — set documenti differenziati, stati per singolo documento.
RF-07
Upload documenti — presigned URL, validazione MIME/dimensione, checksum, anteprima.
RF-08
Motore coerenza — regole su date, importi, intestatari, catastali; gravità bloccante/avviso.
RF-09
Solleciti — job pianificato, soglia per studio, notifica con link.
RF-10
Dashboard pratica — stato documentale, anomalie, giorni di fermo.
Demo 2: pratica reale con tre parti. Un link, tre checklist, upload da mobile, anomalia rilevata su un importo discordante.
Sprint 3Atto, export, sicurezza e consegnaSettimane 5–6

Generazione dell'atto dai dati validati, export, tracciabilità e chiusura. Al termine la piattaforma è consegnabile.

RF-11
Template atto — segnaposto, merge dai dati confermati, gestione campi non risolti.
RF-12
Export — PDF e/o DOCX secondo formato concordato, archiviazione, download tracciato.
RF-13
Archivio e ricerca — filtri per parti, data, tipo atto, stato.
RF-14
Audit log — registro append-only, consultabile dal pannello studio.
RNF
Sicurezza e collaudo — test cross-tenant, rate limit, restore provato, E2E su tre pratiche reali.
DOC
Consegna — manuale tecnico, manuale utente, repository, trasferimento IP.
Demo 3: dalla pratica all'atto esportato, con audit log completo e ripristino backup eseguito davanti a voi.
Fase aggiuntiva, solo con l'opzione A. Mesi 3–5: pagamenti e tipologie di incasso, logiche di business del multitenant (piani, limiti, attivazione studi), accompagnamento alle prime vendite e modifiche richieste dai primi clienti. Resta fuori dai sei sprint di sviluppo.
07

Offerta economica

In entrambe le opzioni: consegna di codice e proprietà intellettuale, documentazione e due mesi di garanzia sui difetti. Nessun canone di manutenzione.

Raccomandata
Opzione A

Partnership

Sviluppo più accompagnamento al go-to-market. Seguiamo le prime vendite, adattiamo le tipologie di pagamento e interveniamo sulle modifiche nei tre mesi di lancio.

MVP — senza pagamenti5.250 €
Pagamenti + logiche di business6.000 €
Canone di manutenzionenessuno
Totale11.250 €
  • ✓Codice sorgente e proprietà intellettuale
  • ✓Documentazione tecnica e manuale utente
  • ✓3 mesi di go-to-market (mesi 3–5)
  • ✓Adattamento tipologie di pagamento
  • ✓Modifiche alla piattaforma durante il lancio
  • ✓2 mesi di garanzia sui difetti
La seconda tranche copre pagamenti e logiche di business del multitenant; il perimetro viene verificato alla fine dell'MVP e ogni voce aggiuntiva fuori elenco si quota a parte. Oltre la garanzia, gli interventi si quotano singolarmente.
Opzione B

Chiavi in mano

Sviluppo e consegna. Costruiamo la piattaforma secondo le specifiche, la consegniamo con documentazione e ci fermiamo. Nessuna consulenza go-to-market.

Sviluppo e consegna7.500 €
Canone di manutenzionenessuno
Totale7.500 €
  • ✓Codice sorgente e proprietà intellettuale
  • ✓Documentazione tecnica e manuale utente
  • ✓2 mesi di garanzia sui difetti
  • —Nessuna consulenza go-to-market
  • —Nessun accompagnamento alle prime vendite
  • —Nessun intervento durante il lancio
L'importo copre l'intero perimetro descritto nei requisiti RF-01 → RF-14. Ciò che sta fuori dal perimetro concordato si quota come sprint aggiuntivo.
Costi di esercizio. Infrastruttura (server, database, storage documenti) stimata in circa 30 €/mese, a carico del cliente. I servizi di intelligenza artificiale usati per l'estrazione dei campi non strutturati sono a consumo e vengono misurati dopo il primo mese di utilizzo reale.
08

Assunzioni, esclusioni e dipendenze

Assunzioni

  • Un tenant per studio notarile; il brand della piattaforma è unico per tutti, senza personalizzazione grafica per studio.
  • Le parti accedono tramite link, senza creare un account.
  • I documenti sono caricati dalle parti o dallo studio; nessuna integrazione con gestionali notarili di terzi.
  • Il formato di export dell'atto viene concordato al kickoff.
  • Il referente unico del cliente è disponibile per le decisioni entro 48 ore.

Esclusioni dal perimetro

  • Firma elettronica e integrazione con provider accreditati: non previste.
  • App mobile nativa (iOS/Android). L'interfaccia è web responsive.
  • White-label: logo e dominio dedicati per singolo studio.
  • Integrazioni con gestionali notarili, registri immobiliari o conservatorie.
  • Migrazione di dati storici da sistemi esistenti.
  • Contenuti giuridici dei template di atto: forniti o validati dal cliente.
  • Pagamenti e logiche di business nell'MVP: sono nella tranche successiva dell'opzione A.
Dipendenze dal cliente. Accessi agli ambienti, dominio, casella per le notifiche transazionali, testi delle informative privacy e conferma del formato di export. Il ritardo su queste voci sposta i tempi in modo proporzionale.
09

Collaudo e accettazione

Funzionale

Esecuzione di tutti i requisiti RF-01 → RF-14 su un set di tre pratiche reali fornite dal cliente, con esito registrato.

Tecnico

Test di accesso cross-tenant (deve fallire), verifica URL firmate e scadenza, ripristino backup eseguito, controllo dei log di audit.

Accettazione

Verbale firmato a fine Sprint 3. I difetti bloccanti vanno chiusi prima del verbale; i non bloccanti entrano nei due mesi di garanzia.

10

Garanzia e post-consegna

Proprietà intellettuale. Alla consegna il cliente riceve titolarità piena del codice, del repository e della documentazione. Solovera non trattiene diritti d'uso, non applica licenze e non pone vincoli tecnici alla manutenzione futura da parte di terzi.