System Architecture

Complete data flow and integration diagram for The Turning Point Home donor management system

Select Architecture

Compare two different approaches to the data layer

Attio CRM

✅ Managed CRM platform
✅ Built-in UI for data management
✅ Pre-built deduplication tools
⚠️ REST API (polling needed)
⚠️ Per-user pricing

Convex

✅ Real-time subscriptions
✅ Instant updates for all 30 users
✅ Complex queries in database
✅ Usage-based pricing
⚠️ Build your own UI

Convex Architecture - Real-Time Data Flow

Hover over any component to see details. All data flows through Convex for instant synchronization.

Real-time webhook

CSV upload

Real-time subscription

Scheduled sync

External Sources

Convex Backend

User Interface

Stripe

Primary payment processor

Resend

Transactional email

Paybee

Butterfly Banquet ticketing

Auctria

Butterfly Banquet auction

Mailchimp

Marketing emails

Manual Entry

Dashboard input

Convex

Real-Time Backend + Database

Actions (webhooks):

• Stripe, Resend, Mailchimp

Mutations (writes):

• Create/update data

• Transactional guarantees

Queries (reads):

• Real-time subscriptions

• Complex aggregations

Crons (scheduled):

• Mailchimp sync (hourly)

• Reconciliation (daily)

Database Tables:

People • Donations • Events

Campaigns • Activities

Dashboard

Next.js + ConvexProvider

~30 staff users

• useQuery (real-time reads)

• useMutation (writes)

• Auto-updates for all users

• No refresh button needed

• Sub-second latency

Real-time webhook

CSV upload → mutation

Hourly cron sync

Direct mutation

Real-time subscriptions

Butterfly Banquet - Atomic Aggregation

1. Upload CSVs: Staff uploads Paybee + Auctria CSVs via dashboard

2. Convex Mutation: Single atomic transaction processes both files

3. Groups by email: Aggregates ticket + auction per person

4. Creates records: Person, Donations, Event Attendance (all atomic)

5. All dashboards update: Instant visibility for all 30 users

Example: Sarah's ticket ($100) + auction ($200) = $300 total donation (calculated atomically)

Real-Time Benefits

Acknowledgements

No duplicate work - all staff see same pending list

Email Tracking

Resend webhook → instant open/click visibility

Campaigns

Progress bars update live as donations arrive

Collaboration

30 users working together seamlessly

Latency Comparison

Stripe donation → Dashboard:<1s

Thank you sent → List update:<1s

Email opened → Activity log:<1s

Manual entry → All users:<1s

Mailchimp opens/clicks:~1hr

Compare to Attio: 5-30 second polling latency

Design Principles

Single Source of Truth

Convex database contains all deduplicated person and donation records with full transaction history. No external data store needed.

Automated Reconciliation

Convex scheduled functions run reconciliation checks. All logic in one place with transactional guarantees.

Source Tracking

Every donation includes original transaction ID and platform for complete audit trail.

Custom Deduplication

Match by email with custom merge logic. Build your own merge UI in dashboard with full control over deduplication strategy.

Integration Patterns

Real-time (Webhooks)

Stripe, Gravity Forms, and Resend webhooks processed directly by Convex actions. All 30 dashboards update instantly via real-time subscriptions.

Batch (CSV Imports)

Paybee and Auctria CSVs processed by Convex mutations. Aggregation and person matching happens in single atomic transaction.

Manual Entry

Dashboard forms call Convex mutations directly. Changes visible to all 30 users instantly via real-time subscriptions.

Real-time Queries

Dashboard uses Convex queries with automatic real-time subscriptions. No polling, no manual refresh needed.

Email Integration Strategy

Transactional (Resend) - Real-time

✅ Thank you emails
✅ Donation receipts
✅ Event confirmations
✅ Real-time webhook tracking
✅ Instant open/click detection
Latency: <1 second

Marketing (Mailchimp) - Synced

📧 Monthly newsletters
📧 Campaign announcements
📧 Event invitations
⚠️ Hourly API sync for engagement
✅ Real-time unsubscribe webhooks
Latency: ~1 hour for opens/clicks

Recommended Implementation Timeline

Phase 1

Historical Data Import

Export 5 years of Stripe donations, clean/dedupe. Write Convex bulk import mutation. Import with transactional guarantees.

Phase 2

Real-time Integration

Create Convex action for Stripe webhooks. Test with small donations. All dashboards update instantly. Enable for all donations.

Phase 3

Event Data

Create Convex mutations for Paybee/Auctria CSV import. Event aggregation happens atomically. Trigger from dashboard UI.

Phase 4

Dashboard Launch

Deploy Next.js dashboard with ConvexProvider. Train staff on real-time acknowledgements. All 30 users see instant updates.

Phase 5

Advanced Features

Build Donors page with real-time search, Campaign tracking with live progress, Fast report generation with Convex queries.

Technical Stack

Frontend

• Next.js 14 (App Router)
• TypeScript
• Tailwind CSS
• React Hooks
• Lucide Icons
• Convex React

Backend / Middleware

• Convex Actions
• Convex Mutations
• Convex Queries
• Convex Crons
• Resend (Email)

Data / Storage

• Convex Database
• Convex File Storage
• Stripe (audit trail)
• Mailchimp (marketing)

Architecture Comparison

Feature	Attio	Convex
Real-time updates	⚠️ Polling required	✅ Native subscriptions
Dashboard latency	5-30 seconds	<1 second
Complex queries	⚠️ API rate limits	✅ Run in database
CRM UI	✅ Built-in	⚠️ Build your own
Deduplication	✅ Built-in merge UI	⚠️ Custom logic
Transaction integrity	⚠️ API-based	✅ ACID guarantees
Pricing model	Per-user (30 × $X)	Usage-based
Setup complexity	Lower	Medium
Developer velocity	Moderate	High (TypeScript-first)
Multi-user collaboration	Good	Excellent (instant sync)