NotionViz: workspace intelligence
An interactive graph that makes invisible database relationships visible: turning Notion workspace architecture into something you can see, navigate, and edit
Case study
NotionViz: workspace intelligence
The Challenge
Notion workspaces in teams and organizations become complex fast. Without visibility into the database relationship graph, teams make schema decisions blindly: creating duplicate databases, building circular dependencies, and leaving orphaned tables that waste attention. There's no native way to audit workspace architecture.
Notion is powerful precisely because it's flexible, but that flexibility has a cost. As workspaces grow, database relationships become an invisible web of connections that nobody can see in full. You know your CRM links to Projects, and Projects link to Tasks, but what links to what else? What breaks if you reorganize? Where are the orphaned databases nobody uses?
NotionViz was born from this question: what if you could see your entire Notion architecture at once? Not a list, not a sidebar: a living graph where databases are nodes and relations are edges, and you can instantly understand the shape of your workspace.
"Every Notion power user has had the experience: you're restructuring a workspace and you have no idea what depends on what. You click through database after database, checking relation properties, trying to build a mental map. It's like navigating a city with no map: you can get around, but you can't see the whole picture."
Without architectural visibility, Notion workspaces accumulate technical debt invisibly. The cost isn't dramatic, it's the slow erosion of workspace coherence that makes every future change harder and every onboarding longer.
Users open dozens of tabs to trace database connections. Schema changes break relations in unexpected places. New team members can't understand how the workspace is organized. Duplicate databases emerge because nobody knew a similar one existed. Workspace audits are manual and never complete.
Research
Personal Pain Point Analysis
Relations Are Invisible Architecture
Notion databases are defined by their relations more than their properties, but relations are only visible one at a time, inside each database. The architecture is there; you just can't see it.
Restructuring Is Terrifying
Without knowing what depends on a database, any structural change feels risky. Users default to leaving things as they are, accumulating workspace debt rather than risking breakage.
12+ databases per mature workspace
Even mid-size teams routinely maintain 12-30 interconnected databases. The relationship graph quickly exceeds what anyone can hold in their head.
API Capability Mapping
Two-Way Relations Are Detectable
Notion's API distinguishes dual_property relations (two-way) from single relations, enabling accurate edge directionality in the graph without heuristics.
Write-Back Is Possible
The API supports creating databases and relation properties: meaning the graph could eventually be an editing surface, not just a viewer.
Paginated search covers full workspace
Notion's search endpoint with object=database filter, paginated, returns all databases accessible via the integration. Full workspace enumeration is achievable.
Key Insights
Architecture is a first-class design material
Database relationships aren't just plumbing: they define how a workspace works. Making them visible turns workspace architecture into something you can design intentionally, not just discover accidentally.
The graph metaphor maps naturally to the domain
Databases are nodes. Relations are edges. Direction matters (one-way vs. two-way). Clusters emerge naturally. The force-directed graph isn't a metaphor, it's the actual structure made visible.
Seeing the whole picture changes behavior
When you can see that one database connects to seven others, or that three databases form an isolated cluster, you make different schema decisions than when you're navigating blind.
Read first, write later
The immediate value is visibility. Editing comes second. Users need to understand their workspace before they can confidently change it.
Goals & Principles
Visualize the full database relationship graph
Every database as a node, every relation as an edge, with force-directed layout that reveals clusters and hubs at a glance.
Enable deep inspection without context-switching
Click any node to see its properties, connections, sample entries, and metadata, without leaving the graph view or opening Notion.
Surface workspace health insights
Detect orphaned databases, over-connected hubs, asymmetric relations, and circular dependencies automatically.
Support visual editing (roadmap)
Allow users to create databases, add relations, and plan schema changes directly from the graph canvas, with impact preview before committing.
Guiding Principles
Legibility over decoration
The graph should make complexity understandable, not add visual complexity. Every visual element earns its place by conveying information.
Notion-native vocabulary
Use Notion's own terminology and mental models. Databases, properties, relations, not 'nodes' and 'edges' in the UI.
Progressive complexity
The graph is useful the moment it loads. Advanced features (health analysis, editing) layer on top without cluttering the initial experience.
Solution Design
Force-Directed Graph with d3-force
Workspace graphs are irregular: some databases have many connections, others have none. Fixed layouts break with different workspace shapes. The visualization needs to adapt automatically.
Implemented d3-force simulation with tuned parameters: -600 repulsion charge, dynamic link distance based on node height, collision detection scaled to node dimensions, and 300 iteration ticks for stable convergence. Nodes are pill-shaped database cards showing name, icon, and property count.
Force-directed layout makes structure legible without manual arrangement. Heavily-connected databases naturally cluster together. Orphans drift to the periphery. The layout itself becomes information: you can read workspace architecture from the shape of the graph.
Rich Database Inspection Panel
Seeing the graph is step one. Understanding what each database contains (its properties, its connections in both directions, its recent activity) requires depth the graph view alone can't provide.
Clicking a node opens a detail panel showing: all properties with types, inbound and outbound connections with property names, sample entries with direct Notion links, and last-edited timestamp. The graph remains visible in the background.
The panel gives depth without losing context. Users can trace a relationship in the graph, then inspect both ends in the panel, building understanding progressively. Direct Notion links let them jump to the source when they need to.
Notion OAuth + Workspace Sync
Users need to grant workspace access securely, and the graph must reflect the current state of their Notion workspace without manual data entry.
Supabase-managed Notion OAuth flow with per-user token storage. On connect, the app enumerates all accessible databases via paginated search, extracts relation properties, deduplicates two-way relations, and renders the complete graph. Re-sync on demand.
Live sync means the graph always reflects reality. OAuth scoping ensures users only see databases their integration has access to. Supabase SSR handles token refresh and multi-user state cleanly.
Outcomes & Impact
Full workspace graph rendered in under 10 seconds via Notion API
Force-directed layout with collision detection handles 50+ database nodes
Two-way relation deduplication eliminates visual noise automatically
Database creation directly from the graph canvas (write-back to Notion)
Workspace architecture becomes a visible, designable artifact instead of an invisible assumption
Orphaned databases and disconnected clusters are immediately obvious from graph shape
New team members can understand workspace structure in minutes instead of weeks
Schema planning moves from 'click through Notion and hope' to 'see the full picture first'
Reflections
What Worked
Force-Directed Layout as Information
The layout algorithm itself communicates structure: clusters, hubs, orphans all emerge from the physics simulation. Users read the graph shape before they read any labels.
API-First Architecture Enabled Iteration
Building on Notion's API rather than scraping or manual input meant the tool could iterate on visualization and interaction without worrying about data accuracy.
Pill-Shaped Nodes Balanced Density and Readability
Custom node shapes that show database name, icon, and property count gave enough information at the graph level to make the overview useful, while keeping nodes compact enough for complex graphs.
Challenges
Notion API Limitations Shape the Product
The API doesn't expose usage frequency, page counts per database, or workspace-level metadata. Health scoring will require inference from available signals rather than direct data.
Force Layout Stability
Non-deterministic force simulation meant the graph looked different on each load. Fixed tick count and consistent initialization solved this but required careful parameter tuning.
Key Learnings
Making invisible structures visible changes how people think about them: the graph view reframes workspace management from navigation to architecture
Force-directed layouts aren't just pretty: they encode real information about system topology that users can read intuitively
Building tools for your own workflow reveals problems no amount of user research can surface: you feel the friction firsthand
API constraints are design constraints: what the platform exposes shapes what your tool can meaningfully do
Read-first, write-later is the right strategy for trust: users need to verify the graph is accurate before they'll trust it for editing