NotionViz: making the structure of a Notion workspace visible
An interactive map of the relationships between Notion databases, built to show at once the dependencies that Notion's own interface only reveals one database at a time.
- Role
- Designer & Developer
- Team
- Solo project
- Duration
- 2 months (ongoing)
- Client
- Personal tool / Open development
The project in one minute
The Challenge
Relations scattered across Notion databases made the overall information structure difficult to inspect.
My contribution
I designed the graph and inspection interface, and built the Notion integration and synchronization pipeline.
Results and scope
Databases and their incoming and outgoing relationships can be inspected together, without tracing each connection in a separate tab.
01Observation
Relations are visible one at a time, inside separate databases.
02Interpretation
A page hierarchy hides the workspace’s dependency structure.
03Design decision
Represent databases as nodes and relations as edges, with inspection in context.
Reading of the project reconstructed from the case study, not an original research artifact.
What remains to be established: The case study does not document a controlled onboarding study or measured time savings.
The Challenge
What I was responsible for
- Identified the gap between Notion's flexibility and its lack of architectural visibility
- Designed the force-directed graph visualization with interactive inspection
- Built the Notion OAuth integration and workspace sync pipeline
- Engineered the d3-force layout with collision-aware, height-responsive node positioning
- Designed the database node UI showing properties, relations, and metadata at a glance
- Architected the workspace health analysis engine (on the roadmap)
Notion makes very flexible structures possible, but offers little overall visibility into dependencies between databases. That makes maintaining or reorganizing a large workspace harder.
In a small Notion workspace it's easy to remember how the databases connect. As projects, CRMs, tasks and archives grow, the relationships become hard to reconstruct without opening every database and checking its properties.
NotionViz comes from that problem, which I ran into while maintaining complex workspaces: use the Notion API to reconstruct those relationships and show them as a navigable graph.
"When you change a workspace's structure, it's easy to know what you're modifying and much harder to know which other databases depend on that choice."
The current product mainly solves a visibility problem. Whether this view actually improves onboarding time or the quality of restructuring is still a question to validate with users.
Reconstructing the relationships means going from one database to the next, checking properties, and holding the dependency map in your head.
Research
Observations from everyday Notion use
Notion shows relations one database at a time
Notion databases are defined more by their relations than by their properties, but relations are visible only one at a time, inside each database. There's no overall view of the structure.
Changing structure is risky when you can't see every dependency
Without knowing what depends on a database, any structural change feels risky. So people tend to leave things as they are, and the workspace accumulates clutter.
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.
What the Notion API exposes
Two-way relations can be reconstructed
Notion's API distinguishes dual_property relations (two-way) from single relations, enabling accurate edge directionality in the graph without heuristics.
The API also allows changing the structure
The API supports creating databases and relation properties, so in the future the graph could also be used to change the structure.
Pagination makes it possible to reconstruct the whole workspace
Notion's search endpoint with an object=database filter, paginated, returns every database the integration can access. So the whole workspace can be enumerated.
Key Insights
Workspace structure is something you can design
Relations between databases determine how the workspace works. Seeing them lets you reason about the structure as a whole, instead of discovering dependencies one page at a time.
A graph fits the way databases are connected
Databases are nodes, relations are edges, and direction matters (one-way or two-way). Clusters emerge on their own: the force-directed graph draws the structure as it is.
Seeing the whole helps with decisions about structure
Seeing that one database connects to seven others, or that three databases form an isolated cluster, exposes dependencies that are otherwise easy to miss. Whether that measurably improves restructuring decisions is a hypothesis to validate with users.
Understand the structure first, change it later
Reading comes first: before changing a workspace you need to understand it. Editing features come later.
Goals & Principles
See every relation between databases on a single map
Every database as a node, every relation as an edge, with force-directed layout that reveals clusters and hubs at a glance.
Explore details without losing context
Clicking a node shows its properties, connections, sample entries and metadata, without leaving the graph or opening Notion.
Find dependencies and structures that are hard to maintain
Detect orphaned databases, over-connected hubs, asymmetric relations, and circular dependencies automatically.
Later, move to visual editing of the structure
Allow users to create databases, add relations, and plan schema changes directly from the graph canvas, with impact preview before committing.
Guiding Principles
Legibility first, graph aesthetics second
The graph should make complexity understandable without adding visual complexity: every graphic element has to carry information.
Use the concepts Notion users already know
The interface uses Notion's terminology (databases, properties, relations) instead of 'nodes' and 'edges'.
Show details as they're needed
The graph is useful the moment it loads. Advanced features (health analysis, editing) layer on top without cluttering the initial experience.
Solution Design
Interactive diagram
Read the workspace through its relationships
Select a node to highlight its connections and read the design decision behind it.
Projects
A project is connected to tasks, people and knowledge. Selecting it exposes the relationships that a page hierarchy hides.
Connected to: Tasks · People · Knowledge
Illustrative database schema. These nodes explain the interaction model, not a real user’s workspace.
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.
Alternatives considered
- Grid or tree layout (predictable but doesn't reflect actual structure)
- Manual positioning (flexible but defeats the purpose of automated visualization)
- Force-directed simulation (adapts to any topology, reveals natural clusters)
I implemented a 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 cards showing the database name, icon and property count.
The force-directed layout makes the structure legible without manual arrangement. Heavily connected databases cluster together, orphans end up at the edges. The shape of the graph already says something about the workspace's architecture.
Trade-off: Force layout can produce different arrangements on each load. Solved by deterministic simulation (fixed tick count, consistent initial positions). Large workspaces (50+ databases) may need performance optimization.
A panel for reading a database in detail
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.
Alternatives considered
- Tooltip on hover (too shallow for meaningful inspection)
- Navigate to Notion (breaks flow, loses graph context)
- Slide-out panel with full metadata (deep inspection without leaving the canvas)
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 adds detail without losing context. You can follow a relation in the graph and then check both ends in the panel. Direct Notion links take you to the source when needed.
Trade-off: Panel requires screen real estate. On smaller viewports, it overlays the graph rather than sitting alongside it.
Notion OAuth and 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.
Alternatives considered
- Manual workspace description (error-prone, immediately outdated)
- CSV export/import (Notion doesn't support graph export)
- OAuth integration with direct API sync (accurate, automatic, keeps up with changes)
Supabase-managed Notion OAuth flow with per-user token storage. On connect, the app enumerates every accessible database via paginated search, extracts relation properties, deduplicates two-way relations and draws the complete graph. Sync can be rerun on demand.
Because it reads data directly from the API, the graph reflects the current state of the workspace. OAuth scoping ensures each user sees only the databases their integration can access. Supabase SSR handles token refresh and multi-user state.
Trade-off: Notion API rate limits require careful pagination. The initial sync for large workspaces takes 5-10 seconds. Webhook-based incremental sync is planned but not yet implemented.
Outcomes & Impact
The current version reconstructs the dependencies between databases and lets you explore them in a single view. Analysis and editing features are still evolving; the effect on onboarding and maintenance remains to be measured.
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)
The workspace structure becomes visible, and you can reason about how to change it
Orphaned databases and disconnected clusters are immediately obvious from graph shape
The graph provides a single place to inspect workspace structure instead of reconstructing it by opening databases one by one
Schema changes can be considered against the visible dependency graph before editing individual databases
What I delivered
- Interactive force-directed graph with React Flow and d3-force
- Notion OAuth integration with paginated workspace sync
- Database inspection panel with properties, connections, and sample entries
- Graph-based database creation with automatic Notion write-back
- Pill-shaped node design following the 'atlas at night' visual direction
- Supabase auth and per-user workspace persistence
Reflections
The limits of Notion's API became part of the design: what isn't exposed can't be reliably inferred by the interface.
What I would change
- Would implement workspace health scoring from the first version, to show right away what the analysis adds
- Would add graph layout persistence so users don't lose manual repositioning between sessions
- Would explore minimap navigation earlier: large workspaces need orientation tools
What worked and what was difficult
What Worked
The graph layout helps read the structure
The layout groups connected databases and exposes hubs and isolated nodes. Whether this helps people understand an unfamiliar workspace still needs to be tested.
Starting from the API made iteration easier
Building on the Notion API, instead of scraping or entering data by hand, let me iterate on visualization and interaction with data that was always correct.
Compact nodes keep even a dense graph readable
Custom nodes showing the database name, icon and property count give enough information to make the overview useful, while staying compact enough for complex graphs.
Challenges
The Notion API limits what the product can do
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.
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.
Next project
SenseKit: research data collection