# Dashboard Guide - Ordio Loop Partner Dashboard

**Last Updated:** 2026-04-10

Complete guide to using the Ordio Loop partner dashboard interface.

**Iconography:** Loop UI uses outline SVGs via a shared registry, not emoji. See [ORDIO_LOOP_ICONOGRAPHY.md](./ORDIO_LOOP_ICONOGRAPHY.md). Admins can open `/partner/icon-preview` to review all icon keys.

## Overview

The partner dashboard is your central hub for managing your affiliate partnership with Ordio. It provides real-time insights into your leads, deals, earnings, and performance metrics.

## Accessing the Dashboard

### Login

1. Navigate to `/v2/pages/partner-login.php`
2. Enter your email address and password
3. Click "Anmelden" (Sign In)
4. You'll be redirected to the dashboard

### Session Management

- **Session Timeout:** 30 minutes of inactivity
- **Remember Me:** Option to stay logged in for 30 days
- **Security:** Session regenerated on login for security

## Dashboard Layout

### Sidebar Navigation

The left sidebar provides access to all dashboard sections:

- **Dashboard** (`/v2/pages/partner-dashboard.php`) - Main overview
- **Leads** (`/v2/pages/partner-leads.php`) - Lead management
- **Earnings** (`/v2/pages/partner-earnings.php`) - Earnings breakdown
- **Referral-URLs** (`/v2/pages/partner-referral-urls.php`) - Link generation
- **Resources** (`/v2/pages/partner-resources.php`) - Asset library (logos, templates)
- **Levels** (`/v2/pages/partner-levels.php`) - Level progression and badges
- **Leaderboard** (`/v2/pages/partner-leaderboard.php`) - Rankings (includes "Dein Rang" when applicable)
- **Programm-Analyse** (`/partner/program-analytics`) - Programm-Kennzahlen (nur Admins; nur Cache)
- **Verwaltung** (`/partner/admin`) - Partner- und Admin-Verwaltung (nur Admins)
- **Settings** (`/v2/pages/partner-settings.php`) - Account settings

### Main Content Area

The main content area displays:

- **KPI Cards** - Key performance indicators at a glance
- **Charts** - Visual data representations
- **Data Tables** - Detailed information lists
- **Action Buttons** - Quick actions and CTAs

### Charts and Empty States

Charts show a friendly empty state when there is no data to display, instead of rendering empty bars or flat lines:

- **Conversion Funnel:** Shows "Noch keine Leads" when all stage counts are zero.
- **MRR Trend (Dashboard & Earnings):** Shows "Noch kein MRR" when there are no months with MRR data.
- **Lead Trend:** Shows "Noch keine Leads" when there are no months or all lead counts are zero.
- **MRR Status / Deal Status:** Show "Keine Daten verfügbar" or "Noch kein MRR/keine Deals vorhanden" when totals are zero.

**Status labels:** Cancelled subscriptions use "Storniert" (not "Gekündigt") consistently across all charts and the deals table.

### Performance

- **Dashboard:** The dashboard-data API includes `recent_leads` (last 10 leads) in its response, so "Letzte Aktivitäten" renders without a separate API call. Single API call.
- **Admin page:** Partners list and audit log are fetched in parallel via `Promise.all`, so total load time is the maximum of the two responses rather than the sum.
- **HTTP cache headers:** Dashboard, Leads, Earnings, Levels, and Leaderboard APIs use `Cache-Control: private, max-age=60` (1 min). Referral-URLs sitemap API uses `max-age=300` (5 min). Repeat visits within the cache window use browser cache.
- **SessionStorage:** Stale-while-revalidate for back-navigation is deferred; not implemented.

### API Call Inventory

| Section        | API(s)                           | Calls on Load |
|----------------|----------------------------------|---------------|
| Dashboard      | affiliate-dashboard-data         | 1             |
| Programm-Analyse (Admin) | affiliate-admin-program-metrics | 1             |
| Admin          | affiliate-admin-list, affiliate-admin-audit | 2 (parallel)  |
| Leads          | affiliate-leads                  | 1             |
| Earnings       | affiliate-earnings              | 1             |
| Levels         | affiliate-levels                | 1             |
| Leaderboard    | affiliate-leaderboard           | 1             |
| Referral-URLs  | affiliate-sitemap-pages         | 1             |
| Resources      | —                                | 0 (server-rendered) |
| Settings       | —                                | 0 (form submit only) |

## Dashboard Sections

### 1. Dashboard Overview

**Location:** `/v2/pages/partner-dashboard.php`

**Features:**

- **KPI Cards:**
  - Gesamt Leads – all referred contacts
  - Qualifizierte Leads – MQL-style count
  - **Deals** – shown as **Offen / Gewonnen** (open HubSpot pipeline deals vs. closed-won deals with MRR); subtitle explains the split
  - Monatliches MRR – partner share; subtitle shows active closed-won deals count

- **MRR Trend Chart:**
  - Line chart showing MRR over last 6 months (Earnings page has full 12 months)
  - Monthly breakdown
  - Visual trend analysis
  - Interactive tooltips

- **Recent Activity:**
  - Latest leads and their status
  - UTM badge (campaign when set; otherwise source / medium when either exists)
  - Recent deal conversions
  - Activity timeline

**Usage:**

- Monitor your overall performance
- Track MRR growth trends
- Review recent activity
- Quick overview of key metrics

### 2. Leads Management

**Location:** `/v2/pages/partner-leads.php`

**Note:** The filter **„Deal“** refers to the contact **lifecycle** (Opportunity), not HubSpot **deal** objects. A short hint on the page links to **Earnings** for pipeline and closed-won subscription deals.

**Features:**

- **Leads Table:**
  - Lead name, company, email, phone
  - Status (Neu, Qualifiziert, Deal, Gewonnen)
  - **Quelle** (UTM source when set; "—" otherwise)
  - **Medium** (UTM medium when set; "—" otherwise)
  - **Kampagne** (UTM campaign when set; "—" otherwise)
  - Referral date

- **Lead-Quellen:**
  - When at least one lead has UTM data: three cards (Quelle, Medium, Kampagne) in a 3-column grid, each with a table and interactive horizontal bar chart
  - When no UTM data: hint card with link to Referral-URLs to use UTM parameters

- **Status Filtering:**
  - Filter by status (All, Neu, Qualifiziert, Deal, Gewonnen)
  - Quick status overview

**Usage:**

- Track all your referred leads
- Monitor lead status changes
- Compare performance by campaign when using UTM parameters
- Identify high-quality leads
- Follow up on leads

### 3. Earnings Overview

**Location:** `/v2/pages/partner-earnings.php`

**Features:**

- **MRR Summary:**
  - Total MRR (all-time)
  - Active MRR (current monthly)
  - Paused MRR
  - Cancelled MRR

- **MRR Trend Chart:**
  - Historical MRR data
  - Growth visualization
  - Monthly breakdown

- **Deals List:**
  - Individual deals with MRR
  - Deal status
  - Subscription information
  - MRR contribution per deal

**Usage:**

- Understand your earnings
- Track MRR growth
- See which deals contribute most
- Plan for future earnings

### 4. Empfehlungs-URLs (Referral URLs)

**Location:** `/v2/pages/partner-referral-urls.php` (sidebar: Empfehlungs-URLs)

**Features:**

- **Schnelllinks (Quick links):** One-click copy for Startseite, Schichtplanung, Zeiterfassung, Preise
- **Seite wählen:** Table of all sitemap pages with search, category filter, and pagination. Per row: **Kopieren** (copy base referral URL) or **Mit UTM anpassen** (set path and scroll to UTM form to add UTM and generate)
- **URL mit UTM-Parametern:** Form with path + all five UTM fields; generate and copy
- **UTM-Vorlagen (Presets):** Newsletter, Social Media, Blog, E-Mail – apply to pre-fill the form
- **Hinweise & Best Practices:** Short guidance (lowercase, dashes, consistent campaign names)
- **Material & Vorlagen:** Logo (SVG) and approved short copy for websites, blogs, email

**UTM Parameters:** `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` (all optional)

**Usage:**

- Copy quick links for key pages
- Search or filter the page table, then copy a link or open "Mit UTM anpassen" to add UTM and generate
- Generate tracking links with UTM for different channels; use presets or custom values; copy generated URL
- Download logo and use approved copy when promoting Ordio

### 5. Resources

**Location:** `/v2/pages/partner-resources.php`

**Features:**

- **Asset Library:**
  - Search and filter by format (SVG, PNG, etc.), product, tag, color
  - Download or embed assets
  - Logos and marketing materials

**Usage:**

- Access full asset library for campaigns
- Download approved materials
- Use for website, blog, or email promotions

### 6. Leaderboard

**Location:** `/v2/pages/partner-leaderboard.php`

**Features:**

- **Top Partners:**
  - Ranked by MRR
  - Anonymous display (names hidden)
  - **Dein Rang:** Shows your rank (#X) and MRR above the list when applicable

- **Leaderboard Stats:**
  - Top 10 partners
  - MRR comparison
  - Ranking changes

**Usage:**

- See how you compare
- Set performance goals
- Motivate improvement
- Track ranking changes

### 7. Levels

**Location:** `/v2/pages/partner-levels.php`

**Features:**

- **Current Level Display:**
  - Large level badge and name (with "manuell" badge when admin has set a manual override)
  - Current MRR share percentage
  - Progress bar to next level
  - Deals needed for advancement

- **Level Progression Tracker:**
  - Visual stepper: Starter → Partner → Pro
  - Requirements for each level
  - Benefits comparison table
  - Current position highlighted

- **Progress to Next Level:**
  - Deals in last 90 days
  - Deals needed for next level
  - Berechnungszeitraum (rolling window date range, e.g. 14.11.2025 – 11.02.2026)
  - Visual progress bar

- **Badge Collection:**
  - All available badges displayed
  - Earned badges highlighted
  - Locked badges with unlock criteria
  - Badge completion percentage

- **Achievements Summary:**
  - Recent achievements timeline
  - Level badges earned
  - Achievement history

- **Next Steps:**
  - Actionable goals
  - Tips for leveling up
  - Quick links to referral URLs

**Usage:**

- Track your level progression
- View earned badges and achievements
- See progress toward next level
- Get actionable tips for improvement
- Understand level requirements and benefits

### 8. Settings

**Location:** `/v2/pages/partner-settings.php`

**Features:**

- **Profile Information:**
  - Name (editable)
  - Email (read-only)
  - Partner ID (read-only)

- **Password Management:**
  - Change password
  - Password requirements
  - Security settings

**Usage:**

- Update your profile
- Change password
- View account information
- Manage security settings

## Data Updates

### Sync Schedule

- **HubSpot Sync:** **Hourly on the app server** (CLI cron — primary). Optional **GitHub Actions** webhook **2×/day** as backup (see `docs/systems/affiliate/CRON_SYNC_RUNBOOK.md`).
- **MRR Calculation:** After each sync
- **Level Updates:** Rolling 90-day window (updated after each sync)
- **Leaderboard:** Reflects cache after each sync (hourly when primary cron is hourly)

### Real-Time Updates

- Dashboard data refreshes on page load
- API calls fetch latest data
- Cached data for performance
- Manual refresh available

## Charts and Visualizations

### MRR Trend Chart

**Technology:** Chart.js

**Features:**

- Line chart visualization
- Monthly data points
- Interactive tooltips
- Responsive design
- Color-coded trends

**Reading the Chart:**

- X-axis: Time (months)
- Y-axis: MRR amount (€)
- Line: Your MRR trend
- Points: Monthly MRR values

### KPI Cards

**Display:**

- Large numbers for quick reading
- Icons for visual identification
- Color coding (green for positive)
- Comparison indicators

## Best Practices

### Regular Monitoring

- **Daily:** Check for new leads
- **Weekly:** Review MRR trends
- **Monthly:** Analyze performance
- **Ongoing:** Review level status (levels use rolling 90-day window)

### Performance Optimization

- **Track Sources:** Use custom URLs to identify best sources
- **Monitor Trends:** Watch MRR chart for growth patterns
- **Follow Up:** Check leads regularly for conversion opportunities
- **Set Goals:** Use leaderboard to set targets

### Data Interpretation

- **MRR Growth:** Upward trend = good performance
- **Lead Quality:** High conversion rate = quality leads
- **Deal Status:** Active deals = ongoing revenue
- **Level Impact:** Higher level = more earnings

## Troubleshooting

### Dashboard Not Loading

**Issue:** Dashboard shows loading spinner indefinitely

**Solutions:**

- Check internet connection
- Refresh the page
- Clear browser cache
- Check browser console for errors
- Contact support if issue persists

### Data Not Updating

**Issue:** Dashboard shows outdated information

**Solutions:**

- Wait for next server sync (normally hourly; backup triggers are less frequent)
- Refresh the page
- Check sync status / cache `last_sync` (ops: `monitor-sync-health.php`)
- Verify HubSpot connection

### Charts Not Displaying

**Issue:** Charts don't render or show errors

**Solutions:**

- Check JavaScript console
- Verify Chart.js is loaded
- Check API endpoint responses
- Refresh the page

### Login Issues

**Issue:** Cannot log in or session expires quickly

**Solutions:**

- Check email/password
- Use "Remember Me" for longer sessions
- Reset password if forgotten
- Clear browser cookies
- Contact support

## Keyboard Shortcuts

- **Refresh:** `Ctrl+R` / `Cmd+R` - Refresh dashboard data
- **Navigation:** Use sidebar links for navigation
- **Search:** Use browser search (`Ctrl+F` / `Cmd+F`) to find content

## Mobile Responsiveness

The dashboard is fully responsive:

- **Desktop:** Full sidebar and wide layout
- **Tablet:** Collapsible sidebar
- **Mobile:** Stacked layout, hamburger menu

## Security Features

- **Session Timeout:** 30 minutes inactivity
- **Password Hashing:** Secure password storage
- **HTTPS:** All connections encrypted
- **CSRF Protection:** Form security tokens
- **Input Validation:** All inputs sanitized

## Related Documentation

- **[Partner Guide](PARTNER_GUIDE.md)** - Complete partner guide
- **[Architecture](ARCHITECTURE.md)** - Technical architecture
- **[API Reference](API_REFERENCE.md)** - API endpoints