Routing & Navigation

Relevant source files

The following files were used as context for generating this wiki page:

• src/routes/tree/$treeId.tsx
• src/lib/nav-sections.ts
• src/lib/nav-sections.test.ts
• src/pages/Home.tsx
• CLAUDE.md
• vite.config.ts
• src/routes/tree/$treeId/place/$placeId.tsx

Vata utilizes a file-based routing system powered by TanStack Router, organized around a core architectural split between the global application context and individual family tree contexts. The routing logic ensures data integrity by managing database connections based on the active route, specifically enforcing a "single-tree-at-a-time" editor experience.

Sources: CLAUDE.md:126-130, README.md:27-30

Routing Architecture

The application's routing is divided into two primary contexts: the outside picker (the Home page) and the inside shell (the specific family tree view). This boundary is enforced by a layout route that handles the lifecycle of the tree-specific SQLite database.

Core Routing Structure

Path Segment	Component/File	Description
/	src/pages/Home.tsx	The tree picker where users can create, import, or open trees.
/tree/$treeId	src/routes/tree/$treeId.tsx	Layout route that manages tree metadata and DB connection.
/tree/$treeId/	src/pages/TreeView.tsx	The home dashboard for a specific opened tree.
/tree/$treeId/individuals	src/pages/IndividualsPage.tsx	List view of all persons in the tree.
/tree/$treeId/individual/$id	—	Detail view for a specific individual.
/tree/$treeId/families	src/pages/FamiliesPage.tsx	List view of family units.

Sources: CLAUDE.md:132-143, src/lib/nav-sections.ts:40-52

The Tree Lifecycle Boundary

The route /tree/$treeId acts as a technical gatekeeper. When a user navigates into a tree path, the layout component:

1. Extracts the treeId from the URL parameters.
2. Retrieves tree metadata from the System DB.
3. Opens the specific Tree DB file on mount.
4. Closes the Tree DB connection on unmount (navigation away from the tree).

Navigation Logic & State

Navigation state is derived from the current URL path to synchronize UI components like the side navigation bar.

Navigation Sections

The application defines a set of top-level navigation sections used in the "Tree Shell" UI. These are mapped to specific route patterns.

export const NAV_SECTIONS = [
  { id: 'home', icon: 'house', labelKey: 'nav.home', to: '/tree/$treeId' },
  { id: 'people', icon: 'user', labelKey: 'nav.individuals', to: '/tree/$treeId/individuals' },
  { id: 'families', icon: 'users', labelKey: 'nav.families', to: '/tree/$treeId/families' },
  { id: 'events', icon: 'calendar', labelKey: 'nav.events', to: '/tree/$treeId/events' },
  { id: 'places', icon: 'map-pin', labelKey: 'nav.places', to: '/tree/$treeId/places' },
] as const;

Sources: src/lib/nav-sections.ts:25-31

Path Resolution

A utility function resolveNavSection determines which section is active based on the third segment of the pathname. This allows both list views and detail views to highlight the same navigation parent (e.g., both /individuals and /individual/$id resolve to the people section).

Native Shell Integration

Since Vata is a Tauri application, the routing system interacts with the native OS menu and events.

Close Tree Event

The layout route listens for a native menu:close-tree event. When triggered, the application programmatically navigates back to the home picker (/). It also invokes a Tauri command set_close_tree_enabled to toggle the availability of the "Close Tree" menu item in the native OS menu bar based on whether a tree is currently active.

Configuration & Tooling

The routing system is integrated into the build pipeline via Vite and TanStack Router plugins.

• Vite Configuration: The TanStackRouterVite plugin manages automatic route generation from the src/routes directory into src/routeTree.gen.ts.
• Path Aliases: Vite is configured with several path aliases (e.g., $components, $db-tree) to simplify imports within route files.
• Environment-Specific Routes: Debug drawers and development-only routing helpers are conditionally included using import.meta.env.DEV to ensure they are excluded from production builds.

Sources: vite.config.ts:21-48, src/routes/tree/$treeId.tsx:12-14

Conclusion

Routing in Vata serves as the primary mechanism for state synchronization between the UI, the native desktop shell, and the underlying SQLite database architecture. By leveraging file-based routing and layout components, the application ensures that database resources are correctly scoped to the active family tree while providing a seamless navigation experience between global and tree-specific views.