Task: Add web page mechanics

Custom URL Routing System (SiteRoute)

Task

Implement a flexible routing system that allows assigning arbitrary URLs to content. Instead of technical paths like /concepts/clxyz123abc — human-readable /articles/my-first-post.

Architectural Decision

A fallback routing approach at the Next.js level was chosen. All requests to non-existent pages are intercepted by a single entry point, which resolves the path via the database.

Why this way:

• Does not require static regeneration when adding new routes
• Hierarchical structure via parentId — allows building nested paths of any depth
• 1:1 relation with content eliminates duplicates and canonicalization issues

Implementation

Database — a new SiteRoute model:

• path — full path (unique index)
• slug — path segment
• parentId — reference to the parent for hierarchy
• kBConceptId — link to the knowledge base concept
• Compound index parentId + slug ensures slug uniqueness within a parent

Next.js — fallback rewrite in next.config.js redirects /:path* to /_fallback/[...path].tsx.

Handler — receives the current path, queries SiteRoute via GraphQL, renders the corresponding page or returns a 404.

Virtual uri field — added to KBConcept at the GraphQL schema level. Returns a custom path if a SiteRoute exists, otherwise the standard /concepts/{id}. All link components automatically use this field.

Technical Details

• GraphQL resolvers: siteRoute, siteRoutes, createSiteRoute
• Components: ConceptLink, PostLink, TaskLink, WorkLogLink
• SEO headers: canonical URL is generated from uri
• Server-side data preload for SSR

Result

The haih-agent engine has received a full-fledged SEF (search-engine-friendly) URL system with hierarchy support, no URL structure limitations, and automatic integration into all existing components.