template-saas/docs/05-frontend/FRONTEND-ROUTING.md

Frontend Routing - Template SaaS

Versión: 1.0.0 Actualizado: 2026-01-25 Router: React Router DOM v7.1.1

---

Arquitectura de Routing

El sistema de routing está basado en React Router v6/7 con guards de protección para controlar el acceso a las rutas según el estado de autenticación y rol del usuario.

Archivo Principal

apps/frontend/src/router/index.tsx

---

Guards de Protección

Guard	Descripción	Redirección
GuestRoute	Solo usuarios no autenticados	→ /dashboard si está autenticado
ProtectedRoute	Requiere autenticación	→ /auth/login si no está autenticado
SuperadminRoute	Requiere rol superadmin	→ /dashboard si no tiene rol

---

Mapa de Rutas Completo

1. Rutas Públicas

Ruta	Componente	Guard	Descripción
/	Navigate	-	Redirect a /auth/login

2. Rutas de Autenticación (/auth)

Layout: AuthLayout Guard: GuestRoute

Ruta	Componente	Descripción
/auth/login	LoginPage	Formulario de inicio de sesión
/auth/register	RegisterPage	Formulario de registro
/auth/forgot-password	ForgotPasswordPage	Recuperación de contraseña

3. Rutas de Dashboard (/dashboard)

Layout: DashboardLayout Guard: ProtectedRoute

3.1 Rutas Core

Ruta	Componente	Descripción
/dashboard	DashboardPage	Dashboard principal con métricas
/dashboard/settings	SettingsPage	Configuración de cuenta
/dashboard/billing	BillingPage	Gestión de suscripción (Stripe)
/dashboard/users	UsersPage	Gestión de usuarios del tenant
/dashboard/ai	AIPage	Panel de control AI/LLM
/dashboard/storage	StoragePage	Gestión de archivos
/dashboard/webhooks	WebhooksPage	Configuración de webhooks
/dashboard/audit	AuditLogsPage	Registro de auditoría
/dashboard/feature-flags	FeatureFlagsPage	Feature toggles
/dashboard/whatsapp	WhatsAppSettings	Config WhatsApp Business

3.2 Rutas de Sales (/dashboard/sales)

Ruta	Componente	Parámetros	Descripción
/dashboard/sales	SalesPage	-	Dashboard de ventas
/dashboard/sales/leads	LeadsPage	-	Listado de leads
/dashboard/sales/leads/:id	LeadDetailPage	id: string	Detalle de lead
/dashboard/sales/opportunities	OpportunitiesPage	-	Pipeline de oportunidades
/dashboard/sales/opportunities/:id	OpportunityDetailPage	id: string	Detalle de oportunidad
/dashboard/sales/activities	ActivitiesPage	-	Actividades de ventas

3.3 Rutas de Commissions (/dashboard/commissions)

Ruta	Componente	Parámetros	Descripción
/dashboard/commissions	CommissionsPage	-	Dashboard de comisiones
/dashboard/commissions/schemes	SchemesPage	-	Esquemas de comisiones
/dashboard/commissions/entries	EntriesPage	-	Entradas de comisiones
/dashboard/commissions/periods	PeriodsPage	-	Períodos de pago
/dashboard/commissions/my-earnings	MyEarningsPage	-	Mis ganancias

4. Rutas de Superadmin (/superadmin)

Layout: DashboardLayout Guard: SuperadminRoute

Ruta	Componente	Parámetros	Descripción
/superadmin	Navigate	-	Redirect a /superadmin/tenants
/superadmin/tenants	TenantsPage	-	Listado de tenants
/superadmin/tenants/:id	TenantDetailPage	id: string	Detalle de tenant
/superadmin/metrics	MetricsPage	-	Métricas del sistema

5. Ruta de Onboarding

Ruta	Componente	Guard	Descripción
/onboarding	OnboardingPage	ProtectedRoute	Wizard de onboarding (4 pasos)

6. Ruta 404 (Catch-All)

Ruta	Componente	Descripción
*	Navigate	Redirect a /

---

Diagrama de Navegación

                    ┌─────────────────┐
                    │       /         │
                    │  (redirect)     │
                    └────────┬────────┘
                             │
                             ▼
          ┌──────────────────┴──────────────────┐
          │                                     │
          ▼                                     ▼
┌─────────────────┐                   ┌─────────────────┐
│   /auth/*       │                   │  /dashboard/*   │
│  (GuestRoute)   │                   │ (ProtectedRoute)│
├─────────────────┤                   ├─────────────────┤
│ login           │◄─────────────────►│ (index)         │
│ register        │   login/logout    │ settings        │
│ forgot-password │                   │ billing         │
└─────────────────┘                   │ users           │
                                      │ ai              │
                                      │ storage         │
                                      │ webhooks        │
                                      │ audit           │
                                      │ feature-flags   │
                                      │ whatsapp        │
                                      │                 │
                                      │ sales/*         │
                                      │ ├─ (index)      │
                                      │ ├─ leads        │
                                      │ ├─ leads/:id    │
                                      │ ├─ opportunities│
                                      │ ├─ opportunities/:id │
                                      │ └─ activities   │
                                      │                 │
                                      │ commissions/*   │
                                      │ ├─ (index)      │
                                      │ ├─ schemes      │
                                      │ ├─ entries      │
                                      │ ├─ periods      │
                                      │ └─ my-earnings  │
                                      └────────┬────────┘
                                               │
                                               │ (superadmin only)
                                               ▼
                                      ┌─────────────────┐
                                      │ /superadmin/*   │
                                      │(SuperadminRoute)│
                                      ├─────────────────┤
                                      │ tenants         │
                                      │ tenants/:id     │
                                      │ metrics         │
                                      └─────────────────┘

---

Layouts

AuthLayout

• Ubicación: src/layouts/AuthLayout.tsx
• Uso: Rutas de autenticación (/auth/*)
• Características:
  • Diseño de 2 columnas (branding + formulario)
  • Responsive para móvil
  • Sin sidebar ni navegación

DashboardLayout

• Ubicación: src/layouts/DashboardLayout.tsx
• Uso: Dashboard y Superadmin
• Características:
  • Sidebar fijo con navegación
  • Top bar con usuario y notificaciones
  • Contenido principal con scroll
  • Menú dinámico según rol
  • Outlet para rutas hijas

---

Flujos de Navegación

Flujo de Autenticación

Usuario no autenticado
    │
    ├─► /dashboard → redirect → /auth/login
    │
    └─► /auth/login → login exitoso → /dashboard

Flujo de Onboarding

Nuevo usuario (post-registro)
    │
    └─► /onboarding
        │
        ├─ Step 1: CompanyStep (info empresa)
        ├─ Step 2: PlanStep (selección plan)
        ├─ Step 3: InviteStep (invitar usuarios)
        └─ Step 4: CompleteStep → /dashboard

Flujo de Superadmin

Usuario con role=superadmin
    │
    ├─► /dashboard/* → acceso normal
    │
    └─► /superadmin/* → acceso permitido
            │
            └─ /superadmin/tenants/:id → detalle tenant

---

Parámetros Dinámicos

Ruta	Parámetro	Tipo	Descripción
/dashboard/sales/leads/:id	id	string (UUID)	ID del lead
/dashboard/sales/opportunities/:id	id	string (UUID)	ID de la oportunidad
/superadmin/tenants/:id	id	string (UUID)	ID del tenant

Uso en Componentes

import { useParams } from 'react-router-dom';

function LeadDetailPage() {
  const { id } = useParams<{ id: string }>();
  // id contiene el UUID del lead
}

---

Estado de Autenticación

Store: auth.store.ts

interface User {
  id: string;
  email: string;
  first_name: string;
  last_name: string;
  role: string;        // 'user' | 'admin' | 'superadmin'
  tenant_id: string;
}

interface AuthState {
  user: User | null;
  accessToken: string | null;
  refreshToken: string | null;
  isAuthenticated: boolean;
  isLoading: boolean;
}

---

Resumen de Rutas

Portal	Cantidad	Guard
Auth	3 rutas	GuestRoute
Dashboard Core	10 rutas	ProtectedRoute
Dashboard Sales	6 rutas	ProtectedRoute
Dashboard Commissions	5 rutas	ProtectedRoute
Superadmin	3 rutas	SuperadminRoute
Onboarding	1 ruta	ProtectedRoute
Total	28 rutas	-

---

Documentación generada - Template SaaS v1.0.0