# Estructura de URL

# Propósito

Este documento mapea el inventario de pantallas (screen-inventory.md) a las rutas de SvelteKit. Define la jerarquía completa de URL de la plataforma e identifica qué rutas son públicas, autenticadas, capaces de funcionar sin conexión o exclusivas de móvil.

SvelteKit usa enrutamiento basado en archivos en src/routes/. Los grupos de rutas (group) afectan al anidamiento de la maquetación, pero no aparecen en la URL. Los segmentos dinámicos usan [param]. Esta estructura es el puente entre la arquitectura de la información y la implementación.

# Arquitectura de rutas

La aplicación usa seis layout groups de SvelteKit (grupos de rutas que comparten un marco, sin afectar la URL), cada uno con un marco de navegación distinto:

Cada grupo envuelve un +layout.svelte que define el marco de navegación de todas las rutas que contiene.

# Mapa de rutas

# Páginas públicas — (public)

No requieren autenticación. Llevan la identidad visual de la organización, pero son de acceso público.

Notas:

• /p/ y /o/ son prefijos cortos para los perfiles públicos: mantienen las URL limpias para compartirlas en redes sociales, materiales impresos y SMS.
• /donate/[formId] es la ruta pública más sensible a la latencia: tiene que cargar rápido en dispositivos de gama baja y con conexiones lentas. Se prerrenderiza siempre que se pueda.
• Las páginas públicas de eventos se pueden compartir por URL sin necesidad de iniciar sesión. El formulario de confirmación de asistencia en /events/[eventId]/rsvp recoge la información sin requerir autenticación.

# Autenticación — (auth)

Pantallas del flujo de autenticación. Usan una maquetación mínima y enfocada: sin barra lateral, sin navegación de la aplicación.

Notas:

• /login detecta si hay passkey disponible y selecciona automáticamente el flujo adecuado. /login/fallback es para dispositivos sin soporte de passkey, o para cuando la persona lo pide explícitamente.
• Todas las rutas de autenticación funcionan en móvil: autenticarse es la primera experiencia de la mayoría de los usuarios.
• /register es el flujo de alta del passkey posterior a aceptar la invitación inicial.

# Aplicación autenticada — (app)

La aplicación principal. Usa el marco de navegación completo (barra superior + barra lateral en escritorio, pestañas inferiores en móvil). Todas las rutas requieren autenticación y el rol las bloquea: la plantilla de rol determina a qué rutas puede acceder cada persona. Entrar a una ruta fuera del propio rol devuelve un 404 (no un 403: las funcionalidades restringidas son invisibles, no prohibidas).

# Paneles

Enrutamiento de la pantalla de inicio: cada arquetipo tiene un panel por defecto. Cuando alguien entra a /dashboard (o inicia sesión), el servidor lo redirige al panel que le corresponde por su rol:

• Administrador de la organización → /dashboard
• Director de comunicaciones → /dashboard/communications
• Director de finanzas → /dashboard/fundraising
• Director de campo → /dashboard/field
• Coordinador de voluntarios → /dashboard/volunteers
• Gestor de datos → /dashboard/data
• Candidato → /dashboard/candidate
• Líder de equipo → /dashboard/team
• Voluntario → /shifts (no es un panel: va directo a los turnos)
• Simpatizante → redirigido al (portal), en /portal

# Personas / CRM

Notas:

• El asistente de importación de datos (de CRM-008 a CRM-011) usa una progresión de URL de varios pasos. Cada paso es una URL distinta, para que el estado del asistente se pueda guardar en marcadores y compartir.
• /people/[contactId] carga datos parciales sin conexión (contactos en caché), pero no puede guardar ediciones sin conexión.

# Operaciones de campo

Notas:

• Las rutas /field/scripts se comparten entre el trabajo de campo y las jornadas de llamadas. Los guiones se crean aquí y las campañas los referencian.
• Todas las pantallas de gestión de campo son preferentemente de escritorio. El trabajo de campo real (tocar puertas, llamar, inscribir) ocurre en el modo de campo, que es un layout group aparte.

# Recaudación de fondos

# Comunicaciones

# Redes sociales

Notas:

• Las redes sociales son una ruta de primer nivel (/social) en vez de ir anidadas bajo /communications, porque son un área funcional distinta en la barra lateral (la sección de Prensa del Director de comunicaciones).
• La vista previa por plataforma (SOCIAL-006) es un componente dentro del redactor de publicaciones, no una ruta aparte.

# Eventos

Notas:

• /events/[eventId] es la vista de detalle de solo lectura; /events/[eventId]/manage es el formulario de edición. Así se evita sobrecargar la misma URL con el estado de ver/editar.
• /events/[eventId]/check-in es una de las pocas rutas autenticadas que funciona por completo sin conexión. Descarga los datos de las personas inscritas al cargar y funciona desconectada.

# Activismo

Notas:

• Las páginas de acción de cara al público (/action/[actionId], /petition/[petitionId]) están en el grupo (public). Estas rutas del personal son para crear y gestionar las campañas.
• La vista previa de mensajes generados por IA (ACT-007) es un componente dentro de la página pública de acción, no una ruta del personal aparte.

# Prensa y medios

# GOTV y día de elecciones

Pantallas de GOTV en modo de campo: GOTV-008, GOTV-009 y GOTV-010 (ficha de puerta, lista de recorrido y llamadas de seguimiento de GOTV) están en el grupo (field-mode), no aquí.

Pantallas de GOTV de cara al voluntario: GOTV-011 (solicitud de transporte), GOTV-014 (registro de entrada del observador electoral) y GOTV-015 (reporte de problemas) están bajo /shifts/... — ver las pantallas del voluntario más abajo.

# Mensajería

Hilos contextuales: de MSG-008 a MSG-011 (hilos de evento, de turno, de problema y de donación marcada) se abren desde su contexto padre (por ejemplo, la página de detalle de un evento muestra una pestaña «Discusión» que renderiza el hilo contextual en línea). Comparten el componente de vista de conversación, pero se llega a ellos desde la entidad padre, no desde la bandeja de entrada de mensajes.

Vistas propias del candidato: MSG-012 (vista de informes) y MSG-013 (cola de aprobaciones) reutilizan la maquetación de mensajes, pero con vistas filtradas: | /messages?view=briefings | MSG-012 | Vista de informes del candidato | Parcial | | /approvals | MSG-013 | Cola de aprobaciones del candidato | No |

# Voluntarios (pantallas del coordinador)

# Pantallas de autoservicio del voluntario

Son las pantallas que voluntarios y líderes de equipo ven para su propio trabajo.

Notas:

• /shifts es el inicio del voluntario. Cuando un voluntario entra a la raíz (/), se le redirige aquí.
• La acción «Iniciar turno» desde /shifts/[shiftId] lleva a la persona al grupo (field-mode).

# Pantallas de GOTV para voluntarios

Pantallas que voluntarios y líderes de equipo usan durante las operaciones de GOTV, fuera del modo de campo.

# Alianza

# Ajustes

# Ayuda y soporte

# Perfil y preferencias de usuario

# Modo de campo — (field-mode)

Marco de pantalla completa exclusiva. Sin barra lateral, sin pestañas inferiores, sin navegación estándar. Solo la barra superior de campo (estado de sincronización, cronómetro del turno) y la navegación entre tareas (anterior/siguiente/terminar turno).

Todas las rutas del modo de campo requieren un turno activo. Entrar a una URL del modo de campo sin turno activo redirige a /shifts.

Notas:

• Las URL del modo de campo llevan el ID del turno o de la sesión, para que una aplicación que se cierre inesperadamente pueda retomar exactamente donde se quedó.
• El modo de campo del trabajo de campo es el más complejo: admite vista de lista, vista de mapa y fichas de puerta individuales. El voluntario avanza linealmente por la lista de recorrido, pero puede alternar entre la vista de lista y la de mapa.
• El modo de campo de las jornadas de llamadas no funciona sin conexión (requiere conectividad para llamar).
• El modo de campo de GOTV es una variante simplificada del de trabajo de campo, con un guion y una ficha de puerta propios de GOTV.

# Portal de simpatizantes — (portal)

Marco de navegación mínimo para simpatizantes. Maquetación separada de la aplicación principal: sin barra lateral, sin funcionalidades del personal. Un portal personal sencillo.

Notas:

• El portal de simpatizantes usa autenticación por enlace mágico por defecto (poca fricción). Las funciones completas de la cuenta (modificar donaciones recurrentes, actualizar métodos de pago) requieren passkey o inicio de sesión por correo.
• Las rutas del portal van bajo el prefijo /portal para separarlas del espacio de nombres de la aplicación principal.

# Asistentes de puesta en marcha — (wizard)

El marco del asistente sustituye la barra lateral por indicadores de pasos. Los elementos permanentes globales (barra superior, sincronización, notificaciones) se mantienen.

Notas:

• Cada asistente gestiona el estado de sus pasos en el componente, no en segmentos de la URL. La URL se queda en /wizard/org-setup durante todos los pasos: el avance se guarda en el estado del componente y se persiste en el servidor.
• /wizard/volunteer-onboarding es el único asistente de prioridad móvil. Todos los demás son preferentemente de escritorio.
• Los asistentes se pueden abandonar y retomar. Volver a la URL del asistente lo retoma en el último paso completado.

# Estructura de archivos de SvelteKit

La jerarquía de rutas se mapea al sistema de archivos de SvelteKit:

src/routes/
├── (public)/
│   ├── +layout.svelte              # Marco de página pública (identidad visual mínima)
│   ├── p/[slug]/+page.svelte       # Perfil del candidato
│   ├── o/[slug]/+page.svelte       # Perfil de la organización
│   ├── donate/[formId]/+page.svelte
│   ├── events/[eventId]/
│   │   ├── +page.svelte            # Página pública del evento
│   │   └── rsvp/+page.svelte       # Formulario de confirmación de asistencia
│   ├── action/[actionId]/+page.svelte
│   ├── petition/[petitionId]/+page.svelte
│   ├── volunteer/+page.svelte
│   └── media-kit/+page.svelte
│
├── (auth)/
│   ├── +layout.svelte              # Maquetación del flujo de autenticación
│   ├── login/
│   │   ├── +page.svelte            # Inicio de sesión con passkey
│   │   └── fallback/+page.svelte   # Enlace mágico / OTP por SMS
│   ├── recover/+page.svelte
│   ├── register/
│   │   ├── +page.svelte            # Alta de passkey
│   │   └── trusted-contacts/+page.svelte
│   ├── authorize-device/+page.svelte
│   └── session-expired/+page.svelte
│
├── (app)/
│   ├── +layout.svelte              # Marco de la aplicación (barra superior + barra lateral + pestañas)
│   ├── +layout.server.ts           # Guardia de autenticación, resolución del rol
│   ├── dashboard/
│   │   ├── +page.svelte            # Panel general de la campaña (+ lógica de redirección)
│   │   ├── field/+page.svelte
│   │   ├── fundraising/+page.svelte
│   │   ├── communications/+page.svelte
│   │   ├── volunteers/+page.svelte
│   │   ├── data/+page.svelte
│   │   ├── compliance/+page.svelte
│   │   ├── war-room/+page.svelte
│   │   ├── team/+page.svelte
│   │   ├── candidate/+page.svelte
│   │   └── alliance/+page.svelte
│   ├── people/
│   │   ├── +page.svelte            # Lista de contactos
│   │   ├── [contactId]/
│   │   │   ├── +page.svelte        # Detalle del contacto
│   │   │   └── edit/+page.svelte
│   │   ├── new/+page.svelte
│   │   ├── segments/...
│   │   ├── dedup/...
│   │   ├── import/...
│   │   ├── export/+page.svelte
│   │   ├── data-quality/+page.svelte
│   │   └── tags/+page.svelte
│   ├── field/...                    # Gestión de campo
│   ├── fundraising/...              # Gestión de la recaudación
│   ├── communications/...           # Correo, SMS
│   ├── social/...                   # Redes sociales
│   ├── events/...                   # Gestión de eventos
│   ├── activism/...                 # Campañas de activismo
│   ├── press/...                    # Prensa y medios
│   ├── gotv/...                     # Operaciones de GOTV
│   ├── messages/...                 # Mensajería
│   ├── volunteers/...               # Gestión de voluntarios
│   ├── shifts/...                   # Autoservicio del voluntario
│   ├── team/...                     # Líder de equipo
│   ├── training/...                 # Módulos de capacitación
│   ├── approvals/+page.svelte      # Aprobaciones del candidato
│   ├── alliance/...                 # Gestión de la alianza
│   ├── settings/...                 # Ajustes y administración
│   ├── help/...                     # Base de conocimiento y soporte
│   └── profile/...                  # Perfil y preferencias de usuario
│
├── (field-mode)/
│   ├── +layout.svelte              # Marco del modo de campo (sincronización, cronómetro, navegación)
│   ├── +layout.server.ts           # Guardia de turno activo
│   └── field-mode/
│       ├── canvass/[shiftId]/...
│       ├── phone-bank/[sessionId]/...
│       ├── voter-reg/[sessionId]/...
│       └── gotv/[shiftId]/...
│
├── (portal)/
│   ├── +layout.svelte              # Marco del portal de simpatizantes
│   └── portal/...
│
└── (wizard)/
    ├── +layout.svelte              # Marco del asistente (indicadores de pasos)
    └── wizard/...

# Patrones de enrutamiento

# Guardias de autenticación

Todas las rutas de (app), (field-mode) y (wizard) requieren autenticación, y la hace cumplir +layout.server.ts a nivel de grupo:

• Solicitud sin autenticar → redirige a /login con el parámetro ?redirect=
• Autenticada pero con el rol equivocado → 404 (no 403: las funcionalidades restringidas son invisibles)
• Autenticada pero sin turno activo (modo de campo) → redirige a /shifts

# Redirección a la pantalla de inicio

/ redirige según el rol de cada persona:

• Roles del personal → su panel específico de rol
• Voluntario / Líder de equipo → /shifts
• Candidato → /dashboard/candidate
• Simpatizante → /portal

# Enlaces directos

Todas las pantallas admiten enlace directo por diseño. El modo de campo conserva en la URL la posición exacta dentro de una lista de recorrido (/field-mode/canvass/[shiftId]/door/[voterId]), lo que permite recuperarse de un cierre inesperado y pasar de un dispositivo a otro.

# Rutas que funcionan sin conexión

Las rutas marcadas como capaces de funcionar sin conexión usan un service worker para cachear el marco de la página y una base de datos SQLite local (vía Capacitor) para los datos. La función load de +page.ts de SvelteKit detecta la conectividad y alterna entre traer del servidor y consultar la base de datos local:

• Con conexión: carga de datos estándar desde el servidor
• Sin conexión: carga desde la SQLite local, muestra el distintivo «Sin conexión» y deja las escrituras en cola para sincronizar

Rutas que funcionan sin conexión: todas las de trabajo de campo, inscripción de votantes y GOTV de (field-mode), /events/[eventId]/check-in, /messages (solo lectura), /shifts (en caché) y /training (módulos en caché).

# Comportamiento de las URL en RTL

El modo RTL no afecta a las URL: las rutas siguen siendo LTR sea cual sea el idioma de la interfaz. Del volteo visual de la maquetación se encargan el atributo lang de <html> y las propiedades lógicas de CSS. El soporte de RTL no requiere ningún cambio en las URL.

# Páginas de eventos públicas frente a autenticadas

Los eventos tienen dos patrones de URL:

• /events/[eventId] (pública, en el grupo (public)) — la página pública que se comparte
• /events/[eventId]/manage (autenticada, en el grupo (app)) — la vista de gestión

SvelteKit lo resuelve por precedencia de layout groups: la ruta /events/[eventId] del grupo (public) existe solo como página pública. Las rutas autenticadas de gestión de eventos llevan los sufijos /manage, /rsvps, /check-in y /metrics para evitar la colisión.

# Preguntas abiertas

1. URL personalizadas para los perfiles públicos. ¿Deberían las organizaciones poder configurar slugs propios para sus páginas de perfil de candidato o de organización (por ejemplo, /maria-santos en vez de /p/maria-santos)? Haría falta una ruta comodín que compruebe los slugs personalizados antes de caer al 404.

2. Espacio de nombres de las rutas de API. Las rutas de API de SvelteKit (endpoints de servidor) deberían llevar un prefijo para no colisionar con las rutas de página. Probablemente /api/v1/..., pero eso se solapa con la API REST pública que menciona el documento de arquitectura. Hay que alinear las rutas de servidor de SvelteKit con la API independiente.

3. URL localizadas. ¿Deberían localizarse las rutas de las URL (por ejemplo, /personas en vez de /people en español, o /contacts en francés)? La mayoría de las aplicaciones internacionalizadas mantienen las URL en inglés con el contenido localizado: implementación más simple y enlaces directos consistentes. Pero algunas jurisdicciones pueden tener requisitos sobre el idioma de las URL oficiales.