​
Charity Portal User Guide

The RippleCore Charity Portal enables charities and non-profits to create volunteer opportunities, verify volunteer activities from partner organizations, and manage relationships with corporate partners.

​
Overview

​
What is the Charity Portal?

The Charity Portal is one of four stakeholder applications in the RippleCore ecosystem:
  • Main App - Employee platform for logging kindness, volunteering, donations, and wellbeing
  • Charity Portal - Partner management and volunteer verification (this app)
  • Consultant Portal - Portfolio management for ESG consultants
  • Council Portal - Social value procurement for public sector

​
Who Should Use This Guide?

This guide is for:
  • Charity Administrators - Managing volunteer opportunities and partnerships
  • Verification Officers - Approving volunteer activities
  • Partnership Managers - Building relationships with corporate partners
  • Charity Directors - Overseeing impact metrics and reporting

​
Getting Started

​
Creating Your Charity Account

  1. Navigate to the Charity Portal sign-up page
  2. Enter your email address and password
  3. Provide your charity name (e.g., “Green Earth Foundation”)
  4. Complete registration
Auto-Creation: Your charity profile is automatically created on first sign-in. If you don’t see your dashboard after logging in, try signing out and back in.

​
First-Time Setup Checklist

1

Complete Your Profile

Add your charity logo, description, and contact information
2

Customize Branding

Visit Settings > Branding to customize your portal’s theme (colors, typography, layout)
3

Create Your First Opportunity

Navigate to Opportunities > New Opportunity to create a volunteer position
4

Invite Partner Organizations

Go to Partners > Invite Partner to start building corporate relationships

​
Dashboard Overview

​
Key Metrics

Your dashboard displays real-time metrics:
  • Total Verifications - Lifetime count of approved volunteer activities
  • Pending Verifications - Activities awaiting your review
  • Active Partners - Organizations with active partnership status
  • Total Hours Verified - Cumulative volunteer hours you’ve approved

​
Quick Actions

From the dashboard, you can:
  • Review Verifications - Click any pending verification to approve/reject
  • View Partners - See partner organizations and their activity metrics
  • Access Recent Activities - Quick access to the last 5 verification requests

​
Managing Volunteer Opportunities

​
Creating Opportunities

Navigate to Opportunities > New Opportunity and complete the form:

​
Basic Information

  • Title - Clear, descriptive name (e.g., “Food Bank Sorting”, “Park Cleanup”)
  • Description - Detailed overview of the volunteer work (minimum 20 characters)
  • Category - Select from: Community Service, Environmental, Education, Healthcare, Animal Welfare, Crisis Response, Other

​
Location Details

  • Address - Full street address for the volunteer location
  • City - City name
  • State/Province - State or province
  • Postal Code - ZIP or postal code
  • GPS Coordinates (Optional) - Latitude/longitude for precise check-in validation

​
Scheduling

  • Start Date & Time - When the opportunity begins
  • End Date & Time - When the opportunity concludes
  • Duration - Automatically calculated (e.g., “4 hours”)

​
Volunteer Requirements

  • Skills - Comma-separated list (e.g., “organization, physical fitness, teamwork”)
  • Capacity - Maximum number of volunteers (e.g., 20)
  • Requirements - Age restrictions, physical requirements, certifications needed
QR Codes: After creating an opportunity, a unique QR code is automatically generated for volunteer check-in/check-out. This enables GPS-verified attendance tracking.

​
Managing Existing Opportunities

Click on any opportunity to:
  • View Details - See full opportunity information
  • Download QR Code - Print for on-site check-ins
  • View Participants - See who’s registered and checked in
  • Edit Details - Update information (location, time, capacity)
  • Delete Opportunity - Remove cancelled events (irreversible)

​
Skills-Based Matching

When creating opportunities, specify required skills to enable automatic matching:
  • RippleCore matches volunteers based on their skill profiles
  • Volunteers see a match score (e.g., “85% match”) when viewing opportunities
  • Charities can filter applications by match percentage
Example Skills: communication, leadership, manual labor, first aid, foreign languages, data entry, event planning

​
Partner Management

​
Inviting Partner Organizations

1

Navigate to Partners Page

Click Partners in the main navigation
2

Click 'Invite Partner'

Opens the partner invitation form
3

Search Organizations

Type organization name to search RippleCore’s database
4

Select Organization

Choose from search results
5

Grant Verification Rights

Enable if you want this partner to verify their own employees’ volunteer activities
6

Send Invitation

Partner receives email notification with acceptance link
Rate Limit: You can send a maximum of 10 partner invitations per hour to prevent spam.

​
Partner Status Types

StatusMeaningActions Available
PendingInvitation sent, awaiting acceptanceResend invitation, Cancel
ActivePartnership establishedView metrics, Deactivate
InactivePartnership paused or endedReactivate, Delete

​
Partner Insights

For each partner, view:
  • Total Hours Verified - Cumulative volunteer hours approved
  • Pending Verifications - Activities awaiting review
  • Verification Accuracy - Historical approval rate
  • Top Volunteers - Most active employees from this partner

​
Verification Queue

​
Understanding Verification Tiers

RippleCore uses a multi-tier verification system for volunteer activities:
TierMethodAudit WeightDescription
Tier 30Self-Reported30%Employee logs activity without external verification
Tier 50Photo Evidence50%Employee uploads photo proof
Tier 70Peer Confirmed70%Colleague verifies participation
Tier 90Manager Approved90%Company manager approves activity
Tier 100Charity Verified100%Your verification - highest credibility
Your Role: When you approve a volunteer activity, it upgrades to Tier 100 - the gold standard for compliance evidence. This is critical for ESG reporting, B-Corp certification, and social value procurement.

​
Reviewing Verification Requests

Navigate to Verification > Review Queue to see pending activities.

​
For Each Request, You’ll See:

Volunteer Information
  • Employee name
  • Company (partner organization)
  • Activity details (opportunity title, date, hours)
Evidence Provided
  • GPS Location - Check-in/check-out coordinates (if available)
  • Photos - Visual evidence of participation
  • Self-Report Notes - Employee’s description of their contribution
Verification Actions
  1. Review Evidence - Check GPS coordinates, photos, and notes
  2. Add Verification Notes - Document your decision (optional but recommended)
  3. Approve or Reject:
    • Approve - Upgrades to Tier 100, counts toward partner metrics
    • Reject - Activity remains at original tier, employee is notified
Best Practices:
  • Check GPS coordinates - Verify they match your opportunity location (±100m tolerance)
  • Review photos - Ensure images show the volunteer at your location
  • Document discrepancies - If rejecting, explain why in verification notes
  • Batch process - Handle multiple verifications from the same event together for consistency
Rate Limit: You can approve/reject a maximum of 50 verifications per hour to ensure quality review.

​
Verification Notes Guidelines

When adding verification notes, include:
  • Confirmation details (e.g., “Confirmed attendance via QR check-in at 9:15 AM”)
  • Observed contribution (e.g., “Sorted 500+ food items, assisted 3 families”)
  • Any discrepancies (e.g., “GPS coordinates show 200m from site - may have parked nearby”)
  • Rejection reasons (e.g., “No photo evidence provided, GPS does not match location”)
These notes become part of the audit trail for compliance reporting.

​
Branding Customization

​
Accessing the Theme Editor

Navigate to Settings > Branding to customize your portal’s appearance.

​
Customization Options

​
Color Scheme

  • Primary Color - Main brand color (buttons, links, headers)
  • Accent Color - Secondary highlights
  • Background Colors - Page and card backgrounds
  • Text Colors - Headings, body text, muted text

​
Typography

  • Font Family - Choose from professional font pairings
  • Font Sizes - Adjust readability (small, medium, large)
  • Font Weights - Light, regular, medium, semibold, bold

​
Layout & Spacing

  • Border Radius - Sharp corners (0px) to fully rounded (20px)
  • Spacing Scale - Compact, comfortable, spacious
  • Container Width - Narrow, medium, wide, full

​
Live Preview

As you make changes, the preview pane updates in real-time showing:
  • Dashboard example
  • Opportunity card
  • Verification card
  • Navigation menu

​
Saving Your Theme

  1. Adjust settings in the sidebar
  2. Review in the preview pane
  3. Click Save Theme
  4. Theme persists across all sessions
Branding Persistence: Your theme is stored in the database (charities.branding_config) and applies to all users viewing your charity’s portal pages.

​
Security & Compliance

​
Data Privacy

RippleCore ensures:
  • Multi-Tenant Isolation - You only see data for your charity and partner organizations
  • Encrypted Storage - All data encrypted at rest (PostgreSQL 18)
  • Secure Sessions - 8-hour session expiry with Redis-backed storage
  • GDPR Compliance - Right to access, rectify, and delete personal data

​
Rate Limiting

To protect against abuse, rate limits are enforced:
  • Partner Invitations: 10 per hour
  • Verifications: 50 per hour
  • Opportunity Creation: 20 per hour
If you exceed a limit, you’ll see a 429 Too Many Requests error. Wait for the reset time (shown in error message).

​
Security Headers

Your portal is protected by:
  • Content Security Policy (CSP) - Prevents XSS attacks
  • HSTS - Forces HTTPS connections
  • X-Frame-Options: DENY - Prevents clickjacking
  • X-Content-Type-Options: nosniff - Prevents MIME sniffing

​
Common Workflows

​
Workflow 1: Creating and Promoting an Opportunity

1

Create Opportunity

Navigate to Opportunities > New, fill in details, submit
2

Download QR Code

From opportunity details page, download QR code image
3

Share with Partners

Email QR code to partner organizations or post on opportunity boards
4

Print QR Code

Print and display at volunteer check-in area
5

Monitor Registrations

Check Participants tab to see who’s signed up
6

Verify Attendance

After event, review verification queue for check-in/check-out records

​
Workflow 2: Verifying Volunteer Hours

1

Access Verification Queue

Navigate to Verification from main menu
2

Sort by Date

Review recent activities first (sorted by creation date)
3

Check Evidence

For each activity, verify GPS coordinates, photos, and notes
4

Add Verification Notes

Document your review findings
5

Approve or Reject

Click Approve (Tier 100) or Reject with reason
6

Notify Volunteer

Employee receives automatic notification of verification status

​
Workflow 3: Building Partner Relationships

1

Identify Target Organizations

Research companies aligned with your mission
2

Send Invitations

Use Partners > Invite Partner to send formal invitation
3

Await Acceptance

Partner organization admin reviews and accepts
4

Create Exclusive Opportunities

Design volunteer opportunities tailored to partner’s CSR goals
5

Verify Activities

Provide timely, quality verification for partner’s employees
6

Review Metrics

Monitor partner insights to demonstrate social impact value

​
Reporting & Analytics

​
Available Metrics

​
Partner Insights

  • Total Partners - Active, pending, and inactive counts
  • Verification Stats by Partner - Hours verified, pending count, accuracy rate
  • Top Volunteers - Most active employees from each partner

​
Verification Metrics

  • Total Verifications - Lifetime approved count
  • Pending Queue Size - Current backlog
  • Average Verification Time - Time from submission to approval
  • Approval Rate - Percentage of activities approved

​
Opportunity Performance

  • Participation Rates - Volunteers per opportunity
  • Skills Match Distribution - How well volunteers align with requirements
  • Capacity Utilization - Filled slots vs. total capacity

​
Exporting Data

Phase 2 Feature: CSV export of verification history, partner metrics, and opportunity analytics is planned for Phase 2 deployment. Contact support for manual exports.

​
Troubleshooting

​
Charity Profile Not Found

Symptom: After signing in, you see “No charity profile found” error. Solution:
  1. Sign out completely
  2. Clear browser cache and cookies
  3. Sign back in
  4. Charity profile auto-creates on first authenticated request
If issue persists, contact support with your email address.

​
QR Code Not Generating

Symptom: Opportunity created but no QR code visible. Solution:
  1. Wait 5-10 seconds for asynchronous generation
  2. Refresh the opportunity details page
  3. Check database: SELECT qr_code FROM volunteer_opportunities WHERE id = 'opportunity-id'
Root Cause: QR code generation happens after database insert. If still missing, check server logs.

​
Rate Limit Exceeded

Symptom: Error message “Too many requests. Please try again in X minutes.” Solution:
  1. Note the X-RateLimit-Reset time in error message
  2. Wait until reset time
  3. Retry operation
Prevention: Batch operations (e.g., verify 10 activities at once instead of 50 rapid individual approvals).

​
GPS Coordinates Don’t Match

Symptom: Volunteer’s GPS check-in shows 200+ meters from opportunity location. Possible Reasons:
  1. Parking lot - Volunteer parked nearby and walked to site
  2. GPS drift - Indoor locations may have ±50-100m accuracy
  3. Wrong location - Volunteer checked in at incorrect site
Best Practice: Use 100-meter tolerance before rejecting. If beyond 100m, request photo evidence or manual confirmation.

​
Type Errors After Schema Changes

Symptom: TypeScript errors in code after database schema updates. Solution: 
pnpm db:generate  # Regenerate TypeScript types from schema
pnpm check        # Verify type errors resolved

​
Best Practices

​
Creating Effective Opportunities

Title: Be specific and action-oriented (e.g., “Saturday Park Cleanup” not “Volunteering”)Description: Include:
  • What volunteers will do (specific tasks)
  • What they’ll learn or experience
  • Why this work matters (impact narrative)
  • What to bring (clothing, supplies, skills)
Skills: List 3-5 relevant skills, not just “general volunteering”. This enables better matching.Capacity: Set realistic limits. Consider supervision ratios for complex tasks.Timing: Allow 1-2 weeks lead time for volunteer registration and planning.

​
Verification Quality Standards

Timeliness: Review verification requests within 48 hours to maintain partner satisfaction.Evidence Check: Always verify GPS coordinates (±100m) and review all submitted photos.Documentation: Add verification notes for 100% of approvals and rejections. This creates audit trails.Consistency: Use the same verification criteria across all partners to ensure fairness.Rejection Guidance: If rejecting, provide constructive feedback so volunteers can submit better evidence next time.

​
Partner Relationship Management

Communication: Respond to partner invitations and questions within 24 hours.Exclusivity: Consider creating exclusive opportunities for top partners to strengthen relationships.Feedback Loop: Quarterly check-ins with partners to review metrics and gather improvement suggestions.Recognition: Highlight top volunteers and partners in your communications (with permission).Impact Reports: Share aggregate impact data (e.g., “Your employees contributed 500 hours this quarter, impacting 1,200 beneficiaries”).

​
Support & Resources

​
Getting Help

​
Keyboard Shortcuts

  • Skip to Main Content: Press Tab on page load to reveal skip link
  • Navigation: Tab through menu items, Enter to activate
  • Forms: Tab to next field, Shift+Tab to previous
  • Submit: Enter on buttons, Cmd/Ctrl+Enter in textareas

​
Accessibility Features

The Charity Portal is designed for WCAG 2.1 AA compliance:
  • Screen Reader Support: All content is accessible via NVDA, JAWS, VoiceOver
  • Keyboard Navigation: Full site usable without mouse
  • High Contrast Mode: Supports OS-level high contrast preferences
  • Reduced Motion: Respects prefers-reduced-motion setting
If you encounter accessibility barriers, please report to accessibility@ripplecore.co.uk.

​
Appendix

​
Glossary

Tier 100 Verification: Charity-verified volunteer activity with highest audit credibility (100% weight). Partner Organization: Company or entity with established partnership relationship, whose employees volunteer through your charity. QR Code Check-In: GPS-validated attendance tracking using scannable codes at volunteer sites. Skills-Based Matching: Automatic alignment of volunteer skills with opportunity requirements. Verification Queue: List of volunteer activities awaiting charity approval. Multi-Tenant Isolation: Security architecture ensuring you only access your charity’s data, not other organizations’.

​
Version History

VersionDateChanges
1.02025-11-17Initial charity portal documentation
Last Updated: 2025-11-17 Maintainer: RippleCore Documentation Team Feedback: docs@ripplecore.co.uk