Skip to main content

Frontend Routing Architecture

This document defines the canonical frontend routing model for Asset360 v3.

Clean URL Structure​

  • System: /system/... (using reserved system slug)
  • Organization: /$orgSlug/...
  • Fund: /$orgSlug/f/$fundCode/...

Each scope has a layout route that loads context (RBAC, params) and renders a scoped sidebar. The sidebar generates org/fund-aware links. There is only one settings UI per scope; system users edit via the same tenant screens after switching scope (audited server-side).

Authentication is handled via route guards and middleware, not URL prefixes, providing cleaner, more intuitive URLs.

Frontend-Backend tRPC Route Mapping​

The tRPC router structure mirrors the frontend route structure for consistency:

Organization Routes:

  • Frontend: /$orgSlug/funds → tRPC: trpc.org.funds.*
  • Frontend: /$orgSlug/users → tRPC: trpc.org.users.*
  • Frontend: /$orgSlug/settings → tRPC: trpc.org.settings.*
  • Frontend: /$orgSlug/stats → tRPC: trpc.org.stats.*

Fund Routes:

  • Frontend: /$orgSlug/f/$fundCode/overview → tRPC: trpc.org.fund.overview.*
  • Frontend: /$orgSlug/f/$fundCode/accounting → tRPC: trpc.org.fund.accounting.*
  • Frontend: /$orgSlug/f/$fundCode/portfolio → tRPC: trpc.org.fund.portfolio.*
  • Frontend: /$orgSlug/f/$fundCode/investors → tRPC: trpc.org.fund.investors.*
  • Frontend: /$orgSlug/f/$fundCode/operations → tRPC: trpc.org.fund.operations.*
  • Frontend: /$orgSlug/f/$fundCode/treasury → tRPC: trpc.org.fund.treasury.*

This direct mapping makes it intuitive for developers to find and use the appropriate tRPC procedures for any given frontend route.

High-level structure​

  • System: dashboard, organizations, funds, investors, users, market-data
  • Org: workspace (overview), users, settings, stats, funds (list/select)
  • Fund: overview, operations (eod, snapshots, reconciliations), portfolio (equity, bonds), accounting (accounts, journal, nav), investors, treasury, tools

Implementation notes​

  • TanStack Router file-based routes with nested and pathless layouts
  • Loaders call tRPC v11 queryOptions(); RBAC enforced server-side and mirrored in loaders
  • Deep links missing fundCode redirect to org funds list to select a fund
  • Route guards handle authentication and authorization, eliminating need for URL prefixes

URL Design Principles​

  1. Clean & Intuitive: URLs should be human-readable and memorable

    • ✅ Better: /acme-corp/f/growth-fund/accounting
    • ❌ Worse: /_authenticated/org/acme-corp/fund/growth-fund/accounting

  2. Shareable & Bookmarkable: Users can easily share and bookmark specific views

    • Easy to remember: /acme-corp/f/growth-fund
    • SEO-friendly for public pages

  3. Unified Structure: Single URL pattern for all scopes

    • System: /system/ (reserved slug)
    • Organizations: /acme-corp/, /tech-startup/, etc.
    • Funds: /acme-corp/f/growth-fund/, /tech-startup/f/seed-fund/
    • No special prefixes for different user types

Rationale​

Clean URLs improve user experience, shareability, and SEO while maintaining security through proper route guards. The shorter, more intuitive structure makes the application feel more professional and modern, following patterns used by leading SaaS applications.