Purpose
Explain how PayPress calculates and exposes fundraising campaign state.
Overview
Fundraising is an optional feature on Donation plans. Campaign progress is derived from local donation orders and exposed through safe public snapshots for front-end hydration.
How It Works
The snapshot service calculates campaign metrics from successful donation orders for the plan. Refund amounts reduce net raised. The service returns an allowlisted DTO with metrics, availability, donation controls, and revision data.
Important Components
- Donation plan fundraising settings.
- Orders table as source of truth.
- Snapshot service.
- Public campaign key.
- Snapshot revision.
- REST endpoint DTO.
- Cache invalidation triggers.
Data Flow
Donation/refund/order status change -> snapshot invalidation/revision -> public endpoint returns current campaign state -> front end hydrates metrics and controls.
Security Considerations
Snapshots do not expose donor personal data, raw orders, raw form responses, API keys, webhook secrets, or internal database records.
Known Limitations
No separate fundraising totals table exists. This keeps data accurate but means large campaigns depend on efficient derived calculations and caching strategy.