NotionViz: rendere visibile la struttura di un workspace Notion
Una mappa interattiva delle relazioni tra database Notion, pensata per vedere in una sola volta dipendenze che nell'interfaccia originale sono visibili solo un database alla volta.
- Ruolo
- Designer & Sviluppatore
- Team
- Progetto individuale
- Durata
- 2 mesi (in corso)
- Cliente
- Strumento personale / Sviluppo aperto
Il progetto in un minuto
La Sfida
Le relazioni sparse tra i database Notion rendevano difficile leggere la struttura complessiva delle informazioni.
Il mio contributo
Ho progettato grafo e interfaccia di ispezione, e sviluppato integrazione Notion e pipeline di sincronizzazione.
Risultati e portata
Database e relazioni in entrata e in uscita si possono ispezionare insieme, senza ricostruire ogni collegamento in una scheda separata.
01Osservazione
Le relazioni sono visibili una alla volta, dentro database separati.
02Interpretazione
La gerarchia delle pagine nasconde le dipendenze del workspace.
03Scelta progettuale
Rappresentare database come nodi e relazioni come archi, con ispezione nel contesto.
Lettura del progetto ricostruita dal case study, non un artefatto originale di ricerca.
Cosa resta da verificare: Il case study non documenta uno studio controllato sull’onboarding né un risparmio di tempo misurato.
La Sfida
Di cosa mi sono occupato
- Identificazione del gap tra la flessibilità di Notion e la sua mancanza di visibilità architetturale
- Design della visualizzazione a grafo force-directed con ispezione interattiva
- Sviluppo dell'integrazione Notion OAuth e della pipeline di sync del workspace
- Sviluppo del layout d3-force con posizionamento dei nodi collision-aware e height-responsive
- Design della UI dei nodi database che mostra proprietà, relazioni e metadati a colpo d'occhio
- Architettura del motore di analisi della salute del workspace (in roadmap)
Notion consente di creare strutture molto flessibili, ma offre poca visibilità d'insieme sulle dipendenze tra database. Questo rende più difficile fare manutenzione o riorganizzare un workspace grande.
In un workspace Notion piccolo è facile ricordare come sono collegati i database. Quando crescono progetti, CRM, task e archivi, invece, le relazioni diventano difficili da ricostruire senza aprire ogni database e controllarne le proprietà.
NotionViz nasce da questo problema che ho incontrato nella gestione di workspace complessi: usare le API di Notion per ricostruire quelle relazioni e mostrarle come un grafo navigabile.
"Quando si cambia la struttura di un workspace è facile sapere cosa si sta modificando, molto meno sapere quali altri database dipendono da quella scelta."
Il prodotto attuale risolve soprattutto un problema di visibilità. Se questa vista migliori davvero tempi di onboarding o qualità delle ristrutturazioni è ancora una domanda da validare con utenti.
Per ricostruire le relazioni bisogna passare da un database all'altro, controllare le proprietà e mantenere mentalmente la mappa delle dipendenze.
Ricerca
Osservazioni nate dall'uso quotidiano di Notion
Notion mostra le relazioni un database alla volta
I database Notion sono definiti più dalle relazioni che dalle proprietà, ma le relazioni si vedono solo una alla volta, dentro ciascun database. Manca una vista d'insieme della struttura.
Cambiare struttura è rischioso quando non si vedono tutte le dipendenze
Senza sapere cosa dipende da un database, ogni cambiamento strutturale sembra rischioso. Così si tende a lasciare le cose come sono, e il workspace accumula disordine.
12+ database per workspace maturo
Anche team di medie dimensioni mantengono abitualmente 12-30 database interconnessi. Il grafo di relazioni supera rapidamente ciò che chiunque possa tenere in testa.
Cosa espongono le API di Notion
Le relazioni bidirezionali si possono ricostruire
L'API di Notion distingue le relazioni dual_property (a due vie) dalle relazioni singole, permettendo direzionalità accurata degli archi nel grafo senza euristiche.
Le API permettono anche di modificare la struttura
L'API supporta la creazione di database e proprietà di relazione: quindi in futuro il grafo potrebbe servire anche a modificare la struttura.
La paginazione permette di ricostruire l'intero workspace
L'endpoint di ricerca di Notion con filtro object=database, paginato, restituisce tutti i database accessibili tramite l'integrazione. Si può quindi enumerare l'intero workspace.
Insight Chiave
La struttura del workspace si può progettare
Le relazioni tra database determinano come funziona il workspace. Vederle permette di ragionare sulla struttura nel suo insieme, invece di scoprire le dipendenze una pagina alla volta.
Il grafo rappresenta bene il modo in cui i database sono collegati
I database sono nodi, le relazioni archi, e la direzione conta (una via o due vie). I cluster emergono da soli: il grafo force-directed disegna la struttura così com'è.
Vedere l'insieme aiuta a prendere decisioni sulla struttura
Vedere che un database si connette ad altri sette, o che tre database formano un cluster isolato, rende visibili dipendenze che altrimenti è facile perdere. Che questo migliori in modo misurabile le decisioni di ristrutturazione è un'ipotesi da validare con gli utenti.
Prima capire la struttura, poi modificarla
La priorità è la lettura: prima di cambiare un workspace bisogna capirlo. Le funzioni di modifica vengono dopo.
Obiettivi e Principi
Vedere in un'unica mappa tutte le relazioni tra database
Ogni database come nodo, ogni relazione come arco, con layout force-directed che rivela cluster e hub a colpo d'occhio.
Esplorare i dettagli senza perdere il contesto
Cliccando un nodo si vedono proprietà, connessioni, entry di esempio e metadati, senza uscire dal grafo o aprire Notion.
Individuare dipendenze e strutture difficili da mantenere
Rilevare automaticamente database orfani, hub sovraconnessi, relazioni asimmetriche e dipendenze circolari.
Arrivare, in seguito, alla modifica visuale della struttura
Permettere agli utenti di creare database, aggiungere relazioni e pianificare cambiamenti di schema direttamente dal canvas del grafo, con anteprima dell'impatto prima di confermare.
Principi guida
Prima la leggibilità, poi l'estetica del grafo
Il grafo deve rendere comprensibile la complessità senza aggiungerne di visiva: ogni elemento grafico deve portare un'informazione.
Usare i concetti che chi usa Notion conosce già
L'interfaccia usa la terminologia di Notion (database, proprietà, relazioni) invece di 'nodi' e 'archi'.
Mostrare i dettagli man mano che servono
Il grafo è utile dal momento in cui si carica. Le funzionalità avanzate (analisi della salute, editing) si aggiungono sopra senza ingombrare l'esperienza iniziale.
Progettazione della Soluzione
Schema interattivo
Leggere il workspace attraverso le relazioni
Seleziona un nodo per evidenziarne i collegamenti e leggere la scelta progettuale.
Progetti
Un progetto è collegato ad attività, persone e conoscenza. Selezionarlo espone le relazioni nascoste dalla gerarchia delle pagine.
Collegato a: Attività · Persone · Conoscenza
Schema di database illustrativo: i nodi spiegano il modello di interazione, non il workspace di un utente reale.
Grafo a forze con d3-force
I grafi dei workspace sono irregolari: alcuni database hanno molte connessioni, altri nessuna. Layout fissi si rompono con forme di workspace diverse. La visualizzazione deve adattarsi automaticamente.
Alternative considerate
- Layout a griglia o ad albero (prevedibile ma non riflette la struttura reale)
- Posizionamento manuale (flessibile ma vanifica lo scopo della visualizzazione automatica)
- Simulazione force-directed (si adatta a qualsiasi topologia, rivela cluster naturali)
Ho implementato una simulazione d3-force con parametri calibrati: carica repulsiva -600, distanza dei link dinamica in base all'altezza del nodo, rilevamento delle collisioni scalato sulle dimensioni del nodo e 300 tick di iterazione per una convergenza stabile. I nodi sono card pill-shaped che mostrano nome del database, icona e numero di proprietà.
Il layout force-directed rende la struttura leggibile senza disposizione manuale. I database molto connessi si raggruppano, gli orfani finiscono in periferia. La forma del grafo dice già qualcosa sull'architettura del workspace.
Compromesso: Il layout force può produrre disposizioni diverse a ogni caricamento. Risolto con simulazione deterministica (tick count fisso, posizioni iniziali coerenti). Workspace grandi (50+ database) potrebbero richiedere ottimizzazione delle performance.
Un pannello per leggere il database nel dettaglio
Vedere il grafo è il primo passo. Capire cosa contiene ciascun database (le sue proprietà, le sue connessioni in entrambe le direzioni, la sua attività recente) richiede una profondità che la vista grafo da sola non può fornire.
Alternative considerate
- Tooltip al hover (troppo superficiale per un'ispezione significativa)
- Navigare a Notion (rompe il flusso, perde il contesto del grafo)
- Pannello a scomparsa con metadati completi (ispezione profonda senza lasciare il canvas)
Cliccando un nodo si apre un pannello di dettaglio che mostra: tutte le proprietà con i tipi, connessioni in entrata e in uscita con i nomi delle proprietà, entry di esempio con link diretti a Notion e timestamp dell'ultima modifica. Il grafo rimane visibile sullo sfondo.
Il pannello aggiunge dettaglio senza far perdere il contesto. Si può seguire una relazione nel grafo e poi controllarne entrambe le estremità nel pannello. I link diretti a Notion portano alla fonte quando serve.
Compromesso: Il pannello richiede spazio schermo. Su viewport più piccoli, si sovrappone al grafo invece di affiancarlo.
OAuth Notion e sincronizzazione del workspace
Gli utenti devono concedere l'accesso al workspace in modo sicuro, e il grafo deve riflettere lo stato corrente del loro workspace Notion senza inserimento manuale di dati.
Alternative considerate
- Descrizione manuale del workspace (soggetta a errori, immediatamente obsoleta)
- Export/import CSV (Notion non supporta l'export del grafo)
- Integrazione OAuth con sync diretto via API (accurato, automatico, segue i cambiamenti)
Flusso Notion OAuth gestito da Supabase con storage dei token per utente. Alla connessione l'app enumera tutti i database accessibili tramite ricerca paginata, estrae le proprietà di relazione, deduplica le relazioni a due vie e disegna il grafo completo. La sincronizzazione si può rilanciare su richiesta.
Leggendo i dati direttamente dall'API, il grafo riflette lo stato attuale del workspace. Lo scoping OAuth garantisce che ogni utente veda solo i database a cui la sua integrazione ha accesso. Supabase SSR gestisce il refresh dei token e lo stato multi-utente.
Compromesso: I rate limit dell'API Notion richiedono una paginazione attenta. Il sync iniziale per workspace grandi richiede 5-10 secondi. Il sync incrementale via webhook è previsto ma non ancora implementato.
Risultati e Impatto
La versione attuale ricostruisce le dipendenze tra database e permette di esplorarle in un'unica vista. Le funzioni di analisi e modifica sono ancora in evoluzione; l'effetto su onboarding e manutenzione resta da misurare.
Grafo completo del workspace renderizzato in meno di 10 secondi via API Notion
Layout force-directed con rilevamento collisioni gestisce 50+ nodi database
Deduplicazione delle relazioni a due vie elimina automaticamente il rumore visivo
Creazione di database direttamente dal canvas del grafo (write-back a Notion)
La struttura del workspace diventa visibile, e si può ragionare su come modificarla
Database orfani e cluster disconnessi sono immediatamente ovvi dalla forma del grafo
Il grafo offre un unico punto da cui ispezionare la struttura del workspace invece di ricostruirla aprendo i database uno a uno
I cambiamenti di schema possono essere valutati contro il grafo delle dipendenze visibile prima di modificare i singoli database
Cosa ho realizzato
- Grafo force-directed interattivo con React Flow e d3-force
- Integrazione Notion OAuth con sync del workspace paginato
- Pannello di ispezione database con proprietà, connessioni ed entry di esempio
- Creazione di database basata sul grafo con write-back automatico a Notion
- Design dei nodi pill-shaped seguendo la direzione visiva 'atlante di notte'
- Autenticazione Supabase e persistenza del workspace per utente
Riflessioni
I limiti dell'API di Notion sono diventati parte del design: ciò che non viene esposto non può essere inferito in modo affidabile dall'interfaccia.
Cosa farei diversamente
- Avrei implementato lo scoring della salute del workspace dalla prima versione, per mostrare subito cosa aggiunge l'analisi
- Avrei aggiunto persistenza del layout del grafo così gli utenti non perdono il riposizionamento manuale tra le sessioni
- Avrei esplorato prima la navigazione minimap: i workspace grandi hanno bisogno di strumenti di orientamento
Cosa ha funzionato e quali difficoltà ho incontrato
Cosa ha funzionato
Il layout del grafo aiuta a leggere la struttura
Il layout raggruppa i database collegati e rende visibili hub e nodi isolati. Resta da verificare quanto questa vista aiuti a capire un workspace che non si conosce.
Partire dalle API ha reso più semplice iterare sul prodotto
Costruire sull'API di Notion, invece di fare scraping o inserire i dati a mano, mi ha permesso di iterare su visualizzazione e interazione con dati sempre corretti.
Nodi compatti per mantenere leggibile anche un grafo denso
Nodi custom che mostrano nome del database, icona e numero di proprietà danno abbastanza informazione per rendere utile la panoramica, restando abbastanza compatti per grafi complessi.
Sfide
Le API di Notion limitano ciò che il prodotto può fare
L'API non espone frequenza d'uso, conteggio pagine per database o metadati a livello di workspace. Lo scoring della salute richiederà inferenza dai segnali disponibili invece di dati diretti.
Stabilità del layout
La simulazione force non deterministica faceva sì che il grafo apparisse diverso a ogni caricamento. Tick count fisso e inizializzazione coerente hanno risolto il problema ma hanno richiesto un'attenta calibrazione dei parametri.
Prossimo progetto
SenseKit: raccolta dati di ricerca