Dynamic Router

Last Updated: May 19, 2025

This document describes the Dynamic Router system in the Typus Development Framework, which provides content-based routing and URL resolution.

Overview

The Dynamic Router is a core component of the Typus Development Framework that enables dynamic, content-driven routing. It allows for:

1. Content-based URL resolution: Map URLs to content items dynamically
2. Hierarchical route structure: Organize routes in a tree structure
3. Route metadata management: Store and retrieve metadata for routes
4. Component mapping: Associate routes with specific frontend components
5. CMS integration: Connect routes to CMS content items

The Dynamic Router bridges the gap between the backend content management system and the frontend application, providing a flexible way to define and manage application routes without code changes.

Architecture

The Dynamic Router follows the standard module architecture of the Typus Development Framework, with clear separation between controllers, services, and data models:

Route Data

The Dynamic Router stores information about each route, including:

• Unique identifier
• URL path
• Human-readable name
• Frontend component to render
• Parent route reference for hierarchical structure
• Order index for sorting
• Metadata (arbitrary JSON)
• Active status
• Creation and update timestamps

Route Hierarchy

Routes are organized in a hierarchical tree structure, where each route can have a parent route and multiple child routes:

This hierarchy allows for:

1. Logical organization of routes
2. Inheritance of properties from parent routes
3. Bulk operations on route subtrees
4. Navigation structure generation

Key Features

Route Resolution

The Dynamic Router can resolve a URL path to a route definition, which includes:

• The route's metadata
• The component to render
• Any associated content

This resolution process is used by the frontend to determine what to display for a given URL.

CMS Integration

The Dynamic Router integrates with the CMS system to:

1. Resolve CMS items by site path
2. Connect routes to content dynamically
3. Provide content metadata to the frontend

Route Management

The Dynamic Router provides a complete set of CRUD operations for managing routes:

• Create new routes
• Read route information
• Update existing routes
• Delete routes
• Reorder routes within the hierarchy

Tree Management

The Dynamic Router can return the route hierarchy as a tree structure, which is useful for:

• Navigation menus
• Sitemaps
• Breadcrumbs
• Route visualization

Functionality

The Dynamic Router provides both public and administrative functionality:

Public Functionality

• Resolving URL paths to route definitions
• Retrieving CMS items by site path

Administrative Functionality

• Managing the complete route hierarchy
• Creating, reading, updating, and deleting routes
• Reordering routes within the hierarchy
• Retrieving the route tree structure

Route Resolution Process

The route resolution process is a key feature of the Dynamic Router. When a request comes in for a specific URL, the following steps occur:

Usage Examples

Resolving a Route

The frontend can resolve a route by making a GET request to /dynamic-routes/resolve?path=/blog/post-1. The response will include:

• Route metadata
• Component to render
• Any associated content

Creating a Route

To create a new route, make a POST request to /dynamic-routes with the following data:

{
  "path": "/blog/new-post",
  "name": "New Blog Post",
  "component": "BlogPostComponent",
  "parentId": "blog-parent-id",
  "orderIndex": 3,
  "meta": {
    "title": "New Blog Post",
    "description": "This is a new blog post",
    "keywords": ["blog", "post", "new"]
  },
  "isActive": true
}

Updating a Route

To update an existing route, make a PUT request to /dynamic-routes/:id with the fields to update:

{
  "name": "Updated Blog Post",
  "meta": {
    "title": "Updated Blog Post",
    "description": "This blog post has been updated"
  }
}

Getting the Route Tree

To get the route hierarchy as a tree, make a GET request to /dynamic-routes/tree. The response will include a nested structure of routes.

Integration with Frontend

The Dynamic Router is designed to work seamlessly with frontend frameworks like Vue.js or React. The frontend can:

1. Request route data for the current URL
2. Render the appropriate component based on the route data
3. Pass content and metadata to the component
4. Handle navigation between routes

Security

The Dynamic Router implements security measures to protect route management:

1. Authentication: Admin endpoints require authentication
2. Role-based authorization: Only users with the admin role can manage routes
3. Validation: All input data is validated using Zod schemas
4. Error handling: Proper error responses for invalid operations

Best Practices

Route Naming

1. Use descriptive names for routes
2. Keep paths simple and user-friendly
3. Use kebab-case for path segments
4. Avoid special characters in paths
5. Consider SEO when designing paths

Route Organization

1. Create a logical hierarchy of routes
2. Group related routes under common parents
3. Limit hierarchy depth to 3-4 levels for maintainability
4. Use orderIndex to control display order

Route Metadata

1. Include SEO metadata (title, description, keywords)
2. Add navigation properties (showInNav, navTitle, navIcon)
3. Include permissions if needed
4. Add custom properties for specific use cases

Conclusion

The Dynamic Router is a powerful component of the Typus Development Framework that enables flexible, content-driven routing. By separating route definitions from code, it allows for dynamic management of application structure without requiring code changes.

The hierarchical nature of routes, combined with metadata and CMS integration, provides a robust foundation for building complex, content-rich applications with sophisticated navigation structures.