# URL Structure

# Purpose

This document maps the screen inventory (screen-inventory.md) to SvelteKit routes. It defines the complete URL hierarchy for the platform, identifying which routes are public, authenticated, offline-capable, or mobile-only.

SvelteKit uses file-based routing in src/routes/. Route groups (group) affect layout nesting but do not appear in the URL. Dynamic segments use [param]. This structure is the bridge between the information architecture and the implementation.

# Route Architecture

The app uses six SvelteKit layout groups, each with a distinct navigation shell:

Each group wraps a +layout.svelte that defines the navigation shell for all routes within it.

# Route Map

# Public Pages — (public)

No authentication required. Tenant-branded but publicly accessible.

Notes:

• /p/ and /o/ are short prefixes for public profiles — keeps URLs clean for sharing on social media, print materials, and SMS.
• /donate/[formId] is the most latency-sensitive public route — must load fast on low-end devices over slow connections. Pre-rendered where possible.
• Public event pages can be shared via URL without requiring login. The RSVP form at /events/[eventId]/rsvp collects information without requiring authentication.

# Authentication — (auth)

Authentication flow screens. These use a minimal, focused layout — no sidebar, no app navigation.

Notes:

• /login detects passkey availability and auto-selects the appropriate flow. /login/fallback is for devices without passkey support or when the user explicitly requests it.
• All auth routes work on mobile — authentication is the first experience for most users.
• /register is the passkey enrollment flow after initial invitation acceptance.

# Authenticated App — (app)

The main application. Uses the full navigation shell (header bar + sidebar on desktop, bottom tabs on mobile). All routes require authentication and are role-gated — the role template determines which routes a user can access. Accessing a route outside one's role returns a 404 (not 403 — restricted features are invisible, not forbidden).

# Dashboards

Home screen routing: Each persona has a default dashboard. When a user navigates to /dashboard (or logs in), the server redirects to their role-appropriate dashboard:

• Org Admin → /dashboard
• Communications Director → /dashboard/communications
• Finance Director → /dashboard/fundraising
• Field Director → /dashboard/field
• Volunteer Coordinator → /dashboard/volunteers
• Data Manager → /dashboard/data
• Candidate → /dashboard/candidate
• Team Lead → /dashboard/team
• Volunteer → /shifts (not a dashboard — goes directly to shifts)
• Supporter → redirected to (portal) at /portal

# People / CRM

Notes:

• The Data Import Wizard (CRM-008 through CRM-011) uses a multi-step URL progression. Each step is a distinct URL so the wizard state is bookmarkable and shareable.
• /people/[contactId] loads partial data offline (cached contacts) but cannot save edits offline.

# Field Operations

Notes:

• /field/scripts are shared between canvassing and phone banking. Scripts are created here and referenced from campaigns.
• All field management screens are desktop-preferred. The actual field work (canvassing, calling, registering) happens in field mode — a separate layout group.

# Fundraising

# Communications

# Social Media

Notes:

• Social media is a top-level route (/social) rather than nested under /communications because it's a distinct functional area in the sidebar (Press section for Comms Director).
• Platform-specific preview (SOCIAL-006) is a component within the Post Composer, not a separate route.

# Events

Notes:

• /events/[eventId] is the read-only detail view; /events/[eventId]/manage is the edit form. This avoids overloading the same URL with view/edit state.
• /events/[eventId]/check-in is one of the few authenticated routes that works fully offline. It downloads attendee data on load and works disconnected.

# Activism

Notes:

• The public-facing action pages (/action/[actionId], /petition/[petitionId]) are in the (public) group. These staff routes are for creating and managing the campaigns.
• AI Message Generation Preview (ACT-007) is a component within the public action page, not a separate staff route.

# Press & Media

# GOTV & Election Day

Field mode GOTV screens: GOTV-008, GOTV-009, GOTV-010 (GOTV door card, walk list, chase calls) are in the (field-mode) group, not here.

Volunteer-facing GOTV screens: GOTV-011 (ride request), GOTV-014 (poll watcher check-in), GOTV-015 (issue report) are under /shifts/... — see Volunteer Screens below.

# Messaging

Contextual threads: MSG-008 through MSG-011 (event, shift, issue, donation flag threads) are accessed from their parent context (e.g., an event detail page shows a "Discussion" tab that renders the contextual thread inline). They share the conversation view component but are navigated to from the parent entity, not from the messages inbox.

Candidate-specific views: MSG-012 (Briefing View) and MSG-013 (Approval Queue) reuse the messages layout but with filtered views: | /messages?view=briefings | MSG-012 | Candidate Briefing View | Partial | | /approvals | MSG-013 | Candidate Approval Queue | No |

# Volunteers (Coordinator Screens)

# Volunteer Self-Service Screens

These are the screens volunteers and team leads see for their own work.

Notes:

• /shifts is the volunteer's home. When a volunteer navigates to the root (/) they are redirected here.
• The "Start Shift" action from /shifts/[shiftId] transitions the user to the (field-mode) group.

# GOTV Volunteer Screens

Screens that volunteers and team leads use during GOTV operations, outside of field mode.

# Alliance

# Settings

# Help & Support

# User Profile & Preferences

# Field Mode — (field-mode)

Full-screen takeover shell. No sidebar, no bottom tabs, no standard navigation. Only the field header (sync status, shift timer) and task navigation (prev/next/end shift).

All field mode routes require an active shift. Navigating to a field mode URL without an active shift redirects to /shifts.

Notes:

• Field mode URLs contain the shift/session ID so that a crashed app can resume exactly where the user left off.
• The canvassing field mode is the most complex — it supports list view, map view, and individual door cards. The volunteer navigates linearly through the walk list but can switch between list and map views.
• Phone banking field mode does not work offline (requires call connectivity).
• GOTV field mode is a simplified variant of canvassing field mode with a GOTV-specific script and door card.

# Supporter Portal — (portal)

Minimal navigation shell for supporters. Separate layout from the main app — no sidebar, no staff features. Simple personal portal.

Notes:

• The supporter portal uses magic link authentication by default (low friction). Full account features (modifying recurring donations, updating payment methods) require passkey or email login.
• Portal routes are under /portal prefix to separate them from the main app namespace.

# Onboarding Wizards — (wizard)

Wizard shell replaces the sidebar with step indicators. Global chrome (header, sync, notifications) remains.

Notes:

• Each wizard has internal step state managed by the component, not by URL segments. The URL stays at /wizard/org-setup throughout all steps — progress is tracked in the wizard component state and persisted server-side.
• /wizard/volunteer-onboarding is the only mobile-primary wizard. All others are desktop-preferred.
• Wizards can be exited and resumed. Navigating back to the wizard URL resumes at the last completed step.

# SvelteKit File Structure

The route hierarchy maps to SvelteKit's file system:

src/routes/
├── (public)/
│   ├── +layout.svelte              # Public page shell (minimal branding)
│   ├── p/[slug]/+page.svelte       # Candidate profile
│   ├── o/[slug]/+page.svelte       # Organization profile
│   ├── donate/[formId]/+page.svelte
│   ├── events/[eventId]/
│   │   ├── +page.svelte            # Public event page
│   │   └── rsvp/+page.svelte       # RSVP form
│   ├── action/[actionId]/+page.svelte
│   ├── petition/[petitionId]/+page.svelte
│   ├── volunteer/+page.svelte
│   └── media-kit/+page.svelte
│
├── (auth)/
│   ├── +layout.svelte              # Auth flow layout
│   ├── login/
│   │   ├── +page.svelte            # Passkey login
│   │   └── fallback/+page.svelte   # Magic link / SMS OTP
│   ├── recover/+page.svelte
│   ├── register/
│   │   ├── +page.svelte            # Passkey enrollment
│   │   └── trusted-contacts/+page.svelte
│   ├── authorize-device/+page.svelte
│   └── session-expired/+page.svelte
│
├── (app)/
│   ├── +layout.svelte              # Main app shell (header + sidebar + tabs)
│   ├── +layout.server.ts           # Auth guard, role resolution
│   ├── dashboard/
│   │   ├── +page.svelte            # Campaign overview (+ redirect logic)
│   │   ├── 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            # Contact list
│   │   ├── [contactId]/
│   │   │   ├── +page.svelte        # Contact detail
│   │   │   └── edit/+page.svelte
│   │   ├── new/+page.svelte
│   │   ├── segments/...
│   │   ├── dedup/...
│   │   ├── import/...
│   │   ├── export/+page.svelte
│   │   ├── data-quality/+page.svelte
│   │   └── tags/+page.svelte
│   ├── field/...                    # Field management
│   ├── fundraising/...              # Fundraising management
│   ├── communications/...           # Email, SMS
│   ├── social/...                   # Social media
│   ├── events/...                   # Event management
│   ├── activism/...                 # Activism campaigns
│   ├── press/...                    # Press & media
│   ├── gotv/...                     # GOTV operations
│   ├── messages/...                 # Messaging
│   ├── volunteers/...               # Volunteer management
│   ├── shifts/...                   # Volunteer self-service
│   ├── team/...                     # Team lead
│   ├── training/...                 # Training modules
│   ├── approvals/+page.svelte      # Candidate approvals
│   ├── alliance/...                 # Alliance management
│   ├── settings/...                 # Settings & admin
│   ├── help/...                     # Knowledge base & support
│   └── profile/...                  # User profile & preferences
│
├── (field-mode)/
│   ├── +layout.svelte              # Field mode shell (sync, timer, nav)
│   ├── +layout.server.ts           # Active shift guard
│   └── field-mode/
│       ├── canvass/[shiftId]/...
│       ├── phone-bank/[sessionId]/...
│       ├── voter-reg/[sessionId]/...
│       └── gotv/[shiftId]/...
│
├── (portal)/
│   ├── +layout.svelte              # Supporter portal shell
│   └── portal/...
│
└── (wizard)/
    ├── +layout.svelte              # Wizard shell (step indicators)
    └── wizard/...

# Routing Patterns

# Auth Guards

All routes in (app), (field-mode), and (wizard) require authentication, enforced by +layout.server.ts at the group level:

• Unauthenticated request → redirect to /login with ?redirect= parameter
• Authenticated but wrong role → 404 (not 403 — restricted features are invisible)
• Authenticated but no active shift (field mode) → redirect to /shifts

# Home Screen Redirect

/ redirects based on user role:

• Staff roles → their role-specific dashboard
• Volunteer / Team Lead → /shifts
• Candidate → /dashboard/candidate
• Supporter → /portal

# Deep Linking

All screens are deep-linkable by design. Field mode preserves the exact position in a walk list via URL (/field-mode/canvass/[shiftId]/door/[voterId]), enabling crash recovery and device handoff.

# Offline-Capable Routes

Routes marked as offline-capable use a service worker to cache the page shell and a local SQLite database (via Capacitor) for data. The SvelteKit +page.ts load function detects connectivity and switches between server fetch and local DB queries:

• Online: Standard server-side data loading
• Offline: Load from local SQLite, display "Offline" badge, queue writes for sync

Offline-capable routes: all (field-mode) canvassing/voter-reg/gotv routes, /events/[eventId]/check-in, /messages (read-only), /shifts (cached), /training (cached modules).

# RTL URL Behavior

URLs are not affected by RTL mode — paths remain LTR regardless of UI language. The lang attribute on <html> and CSS logical properties handle the visual layout flip. No URL changes needed for RTL support.

# Public vs. Authenticated Event Pages

Events have two URL patterns:

• /events/[eventId] (public, in (public) group) — the shareable public page
• /events/[eventId]/manage (authenticated, in (app) group) — the management view

SvelteKit resolves this via layout group precedence: the (public) group's /events/[eventId] route exists only as the public page. Authenticated event management routes include the /manage, /rsvps, /check-in, /metrics suffixes to avoid collision.

# Open Questions

1. Vanity URLs for public profiles. Should tenants be able to configure custom slugs for their candidate/org profile pages (e.g., /maria-santos instead of /p/maria-santos)? This would require a catch-all route that checks for vanity slugs before falling through to 404.

2. API route namespace. The SvelteKit API routes (server endpoints) should be prefixed to avoid collision with page routes. Likely /api/v1/... — but this overlaps with the public REST API mentioned in the architecture doc. Needs alignment between the SvelteKit server routes and the standalone API.

3. Localized URLs. Should URL paths be localized (e.g., /personas instead of /people in Spanish, /contacts in French)? Most internationalized apps keep English URLs with localized content — simpler implementation, consistent deep linking. But some jurisdictions may have requirements around language in official URLs.