Consultant Guide - RippleCore Documentation

Welcome, Michael! 🎯

This guide helps you use RippleCore as a Consultant or Partner managing multiple client organizations. You get portfolio-wide insights, white-label theming, and strategic benchmarking.

Meet Michael: Sustainability consultant, 20+ clients, benchmarking needs. Saves 94% time with multi-client view, branded exports, and strategic insights.

Getting Started

Access the Consultant Portal

URL: https://consultant.yourdomain.com (or your custom domain)

Use your consultant account credentials:

Email + password authentication
Or single sign-on (SSO) if configured

Create Your Profile

On first login, your consultant profile is created automatically:

Linked to your email address
Ready to manage clients immediately
Access all consultant features

Access Dashboard

The consultant dashboard shows:

Portfolio overview (all clients)
Quick actions (invite clients, edit themes)
Navigation to key features

Pro Tip: Bookmark consultant.yourdomain.com/dashboard for quick access to your portfolio overview.

Portfolio Dashboard Overview

Consultant → Dashboard Your central hub for managing all client organizations and viewing portfolio-wide metrics.

Total Clients

Active clients in your portfolio

View count of managed organizations
Quick access to add new clients
See pending invitations

Real-Time Evidence

Aggregated across all clients:

Kindness acts (monthly total)
Volunteer hours (monthly total)
Donations tracked (monthly total)
Wellbeing surveys completed

Avg Compliance Score

Portfolio compliance readiness:

B-Corp average across clients
CSRD readiness metrics
Social Value Act tracking
UN SDG alignment

All We Can Impact

Portfolio global contribution:

Schools supported monthly
Portfolio ranking globally
Lives impacted (estimated)

What You See:

Portfolio Analytics: Real-time aggregation of evidence from all client organizations
Quick Actions: Invite clients, edit themes, view benchmarks
Client List: Table of all managed organizations with key metrics
Performance Indicators: Trends for kindness, volunteer hours, donations, wellbeing

Client Management

Invite Organizations to Your Portfolio

Consultant → Dashboard → Invite Client

Search for Organization

Use the organization search to find companies:

Search by company name
Search by slug (e.g., “acme-corp”)
Minimum 2 characters required

Send Invitation

Once you find the organization:

Click Invite as Client
Add optional personalized message
System sends branded email to organization owner

Track Invitation Status

Monitor invitation status:

Pending: Sent, awaiting acceptance
Accepted: Client relationship active
Declined: Organization declined
Expired: Invitation expired (7 days)

Email Templates: Invitation emails are branded with your consultant profile and include clear accept/decline actions.

View Client Details

Consultant → Clients → [Client Name] Each client has a detailed overview page showing:

Evidence Overview
Organization Info
Compliance Status
Branding

Current month metrics:

Kindness acts logged
Volunteer hours verified
Donations tracked
Wellbeing surveys completed

Trends: Compare to previous month (percentage change)

Client Benchmarking

Consultant → Benchmarks

Current Implementation: The benchmarking dashboard shows portfolio analytics and client rankings. Industry-wide benchmarking comparisons are coming in Phase 2.

Portfolio Analytics Dashboard

Compare performance across your client portfolio:

Evidence Collection
Verification Quality
Wellbeing Trends
Compliance Readiness

Kindness Acts per Employee per Month:View your clients ranked by engagement:

Acts per employee metric
Monthly totals
Performance quartiles
Trend indicators (↗ ↘ →)

Insight: Identify high-performing culture programs to share best practices

Portfolio Rankings

The benchmarks page displays:

Client Performance Table: Sortable by any metric
Quartile Indicators: 🥇 Top, 🥈 Above Avg, 🥉 Below Avg, 🔴 Bottom
Trend Arrows: ↗ Improving, → Stable, ↘ Declining
Best Practices: Extract insights from high performers

Coming Soon: Industry benchmarking (compare your clients to sector averages) is planned for Phase 2.

White-Label Theming

✅ Fully Implemented: Complete visual theme editor with 31 customizable colors, AI-powered generation, and automatic application across web + email.

Visual Theme Editor

Consultant → Clients → [Client] → Branding → Edit Theme Create custom branded themes for each client with the professional theme editor: Features:

31 Color Tokens: Primary, secondary, accent, background, foreground, borders, and semantic colors
Light & Dark Modes: Edit both modes simultaneously with real-time preview
OKLCH Color Space: Professional color system for consistent brightness and saturation
Live Preview: See changes instantly in a sample dashboard
Undo/Redo: Full history for all theme changes
Professional Presets: 4 built-in themes (default, sunset, ocean, forest)

Open Theme Editor

Navigate to client branding page and click Edit ThemeYou’ll see:

Left Panel: 31 color pickers organized by category
Center Panel: Live preview of theme applied to UI components
Top Bar: Light/dark mode toggle, presets, AI generation, save/cancel

Customize Colors

Choose a starting point:

Start from current theme
Pick a professional preset
Use AI generation (see below)

Edit colors:

Click any color swatch to open color picker
Adjust hue, saturation, lightness
Switch between light/dark modes
See live preview update instantly

Preview Theme

Real-time preview shows:

Buttons and form components
Cards and panels
Text hierarchy
Borders and dividers
Semantic colors (success, warning, error)

Switch modes: Toggle between light/dark to verify both

Save Theme

Click Save Theme when satisfied:

Theme saved to database
Applied automatically to client’s app
Compiled to CSS for performance
Email templates updated

AI Theme Generation

Consultant → Branding → AI Theme Dialog Generate complete themes from brand colors using GPT-4:

Open AI Generator

Click Generate with AI button in theme editor

Provide Brand Information

Required:

Primary Color: Client’s main brand color (hex, e.g., #0d1594)

Optional:

Secondary Color: Accent or secondary brand color
Brand Context: Industry, brand personality, target audience
- Example: “Professional healthcare organization, trustworthy, calming”

Review Generated Theme

AI generates:

All 31 color tokens for light mode
All 31 color tokens for dark mode
Harmonious color relationships
Accessible contrast ratios

Preview immediately in theme editor

Refine if Needed

Accept generated theme as-is
Or manually adjust any colors
Regenerate with different context for variations

API Key Required: AI theme generation requires OPENAI_API_KEY environment variable. Contact your administrator if the feature is unavailable.

Rate Limit: AI generation limited to 10 themes per day per consultant to manage API costs. Use strategically for new clients.

Theme Application

What happens automatically when you save a theme:

Database Storage: Theme saved to client_themes table with OKLCH color values
CSS Compilation: Theme compiled to CSS variables at build time for 80% faster loading
Runtime Injection: Theme applied instantly via CSS custom properties
Email Theming: Email templates automatically use theme colors (OKLCH → RGB conversion)
Public Pages: Client compliance dashboards display with branded theme

Client Experience:

Theme loads with the app (no flash of unstyled content)
Consistent branding across all pages
Automatic light/dark mode support
Professional, polished appearance

Bulk Operations

Current Status: CSV upload component and bulk invite API are complete (3 hours). Full UI integration for bulk operations wizard is available as a Phase 2 enhancement (8 hours).

Bulk Client Invitations (Core Complete)

Consultant → Bulk → Invite Clients Invite multiple organizations at once via CSV upload: CSV Format:

organizationId,message
org_123,Join my portfolio
org_456,Let's work together
org_789,Become my client

Process:

Prepare CSV with organization IDs and optional messages
Upload via bulk invite page
System validates CSV (max 500 rows, 1MB file size)
Invitations sent to all organizations
View results: success count, failed count, detailed results

Current Implementation:

✅ CSV upload component
✅ File validation (size, format)
✅ Bulk invite API with rate limiting
✅ Results display

Phase 2 Enhancement (available):

Wizard-style multi-step flow
CSV template download
Preview before sending
Error handling with retry

Export & Reporting

Portfolio Data Export

Consultant → Bulk → Export Portfolio Export portfolio analytics to CSV for external analysis: Export Options:

Format: CSV or JSON
Period: Week, month, quarter, year
Data: Client metrics, evidence totals, compliance scores

CSV Columns:

Client,Kindness Acts,Volunteer Hours,Donations,Compliance Rate
Acme Corp,234,1200,45000,92
TechStart,45,300,12000,67
GreenCo,67,450,18000,73

Use Cases:

Import to Excel/Google Sheets for custom analysis
Create custom charts and presentations
Share metrics with stakeholders
Quarterly business reviews

Strategic Recommendations

Phase 2 Planned: Automated client reports and AI-powered strategic recommendations are planned features. The benchmarking dashboard provides the foundation for manual strategic insights.

Using Benchmark Data for Client Guidance

Current Approach (manual analysis from benchmarks):

Identify Performance Gaps

Use benchmarking dashboard to find:

Low-engagement clients (less than 0.3 acts/employee)
Low verification quality (below 50 score)
Negative wellbeing trends (over 20% negative sentiment)
Compliance gaps (below 75% readiness)

Extract Best Practices

From high-performing clients:

What verification levels do they achieve?
How frequently do employees engage?
What’s their wellbeing sentiment distribution?
How did they reach compliance readiness?

Create Action Plans

Develop client-specific recommendations:

Manager engagement training (for verification)
Department champion programs (for engagement)
Wellbeing intervention strategies (for sentiment)
Compliance roadmap sessions (for frameworks)

Track Progress

Monitor improvements:

Weekly/monthly metric reviews
Benchmark position changes
Trend indicators
Success story extraction

Future AI Recommendations (Phase 2)

Planned features include:

Automated Monthly Reports: Client performance summaries with benchmarking
AI-Generated Insights: Strategic recommendations based on data patterns
Quarterly Business Reviews: Auto-generated presentation decks
Intervention Alerts: Proactive notifications for clients needing support

Public Compliance Dashboards

✅ Implemented: Clients can share white-label compliance dashboards publicly.

Consultant → Clients → [Client] → Settings → Public Dashboard Allow clients to showcase their social impact: Features:

Public URL: yourdomain.com/org/[client-slug]/compliance
White-Label Branding: Client theme applied automatically
Compliance Metrics: B-Corp, CSRD, SDGs, Social Value readiness
Evidence Summary: Kindness, volunteer, donation totals
All We Can Impact: Global contribution tracking

Use Cases:

Client annual reports (ESG section)
Investor relations (social impact evidence)
Recruitment marketing (culture showcase)
Public procurement bids (Social Value Act)
Certification applications (B-Corp, ISO 26000)

Performance & Best Practices

Build-Time Theme Compilation

✅ Implemented: Themes compiled to static CSS at build time for 80% faster loading compared to runtime generation.

How It Works:

Theme saved to database in OKLCH format
Build process converts OKLCH → CSS variables
Static CSS file generated and cached
Client app loads pre-compiled theme instantly

Performance Benefits:

80% faster than runtime theme application
No flash of unstyled content
Better Core Web Vitals: LCP, FID, CLS all improved
CDN-friendly: Static CSS cached at edge

Rate Limiting

The consultant app includes rate limiting for API protection: Limits:

Authenticated: 100 requests/minute
Bulk Operations: 10 requests/minute
AI Generation: 5 requests/minute, 10 themes/day

When You Hit Limits:

429 Too Many Requests response
Retry-After header indicates wait time
Exponential backoff recommended

Troubleshooting

Common Issues

Theme Not Applying to Client App

Symptoms: Client sees default theme instead of custom themeSolutions:

Verify theme saved successfully (check database client_themes table)
Clear browser cache for client app
Rebuild app to compile new theme: pnpm --filter app build
Check console for CSS variable loading errors
Verify organization ID matches between theme and client session

AI Theme Generation Fails

Symptoms: AI generation returns error or blank themeCauses:

Missing OPENAI_API_KEY environment variable
OpenAI API quota exceeded
Invalid API key
Network connectivity issues

Solutions:

Verify OPENAI_API_KEY is set in production environment
Check OpenAI account has available quota
Test API key with curl: curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
Fallback: Use manual theme creation or presets

Client Invitations Not Sending

Symptoms: Organization doesn’t receive invitation emailCauses:

Email service not configured (Resend)
Invalid organization ID
Organization already has active consultant

Solutions:

Verify RESEND_TOKEN environment variable
Check Resend dashboard for email delivery status
Verify organization ID exists: search in database
Check if organization already in another consultant’s portfolio

Portfolio Analytics Showing Zero

Symptoms: Dashboard shows 0 for all evidence metricsCauses:

No active client relationships
Clients have no evidence logged yet
Cache not updated after client invitations accepted

Solutions:

Ensure at least one client invitation is accepted
Wait for clients to log evidence (or use seed data for testing)
Clear Redis cache for consultant: redis-cli DEL "consultant:{id}:*"
Refresh dashboard page

Keyboard Shortcuts

Speed up your workflow with these shortcuts:

Shortcut	Action	Context
`Ctrl+K` (Win) / `⌘K` (Mac)	Quick search	Global
`Ctrl+B`	Open benchmarks	Dashboard
`Ctrl+I`	Invite client	Dashboard
`Ctrl+T`	Open theme editor	Client page
`Ctrl+S`	Save theme	Theme editor
`Ctrl+Z`	Undo theme change	Theme editor
`Ctrl+Shift+Z`	Redo theme change	Theme editor

API Integration

For developers building custom integrations, see the Consultant API Reference for complete API documentation.

Programmatic Client Management

Use the API for automation: Example: Invite clients programmatically

const response = await fetch('/api/invitations/send', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    organizationId: 'org_123',
    message: 'Join my portfolio',
  }),
});

Example: Generate theme with AI

const response = await fetch('/api/theme/generate', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    primaryColor: '#0d1594',
    context: 'Healthcare organization, trustworthy, calming',
  }),
});

See API Reference for all endpoints.

Next Steps

Theme Editor Guide

Deep dive into white-label theming capabilities

Deployment Guide

Deploy the consultant app to production

API Reference

Complete API documentation for integrations

Compliance Frameworks

Learn about B-Corp, CSRD, SDGs, Social Value

Support & Resources

Consultant Support: For partnership inquiries or technical support, contact partners@ripplecore.co.uk. Community:

GitHub Discussions: ripplecore/discussions
Documentation: docs.ripplecore.co.uk

Training:

Theme Editor Tutorial: Video walkthrough
Benchmarking Best Practices: Guide
Client Onboarding: Checklist

Get Started

User Guides

Admin Portal

Compliance & Reporting

All We Can Integration

Deployment

​Welcome, Michael! 🎯

​Getting Started

​Access the Consultant Portal

​Portfolio Dashboard Overview

Total Clients

Real-Time Evidence

Avg Compliance Score

All We Can Impact

​Client Management

​Invite Organizations to Your Portfolio

​View Client Details

​Client Benchmarking

​Portfolio Analytics Dashboard

​Portfolio Rankings

​White-Label Theming

​Visual Theme Editor

​AI Theme Generation

​Theme Application

​Bulk Operations

​Bulk Client Invitations (Core Complete)

​Export & Reporting

​Portfolio Data Export

​Strategic Recommendations

​Using Benchmark Data for Client Guidance

​Future AI Recommendations (Phase 2)

​Public Compliance Dashboards

​Enable Public Sharing

​Performance & Best Practices

​Build-Time Theme Compilation

​Rate Limiting

​Troubleshooting

​Common Issues

​Keyboard Shortcuts

​API Integration

​Programmatic Client Management

​Next Steps

Theme Editor Guide

Deployment Guide

API Reference

Compliance Frameworks

​Support & Resources

Welcome, Michael! 🎯

Getting Started

Access the Consultant Portal

Portfolio Dashboard Overview

Client Management

Invite Organizations to Your Portfolio

View Client Details

Client Benchmarking

Portfolio Analytics Dashboard

Portfolio Rankings

White-Label Theming

Visual Theme Editor

AI Theme Generation

Theme Application

Bulk Operations

Bulk Client Invitations (Core Complete)

Export & Reporting

Portfolio Data Export

Strategic Recommendations

Using Benchmark Data for Client Guidance

Future AI Recommendations (Phase 2)

Public Compliance Dashboards

Enable Public Sharing

Performance & Best Practices

Build-Time Theme Compilation

Rate Limiting

Troubleshooting

Common Issues

Keyboard Shortcuts

API Integration

Programmatic Client Management

Next Steps

Support & Resources