SPARCD Technical Documentation

Sparcd is a mobile-first goal achievement platform that combines evidence-based behavioral psychology with modern cloud infrastructure.

Project: Sparcd - Psychology-Informed Goal Achievement Platform
Last Updated: February 2026
Architecture: Flutter + FastAPI + MongoDB + Redis + Firebase
Monetization: Freemium via RevenueCat (Free/Pro tiers)

Executive Summary

Sparcd is a mobile-first goal achievement platform that combines evidence-based behavioral psychology with modern cloud infrastructure. The system breaks large goals into daily micro-actions and personalizes every interaction: notification timing, task difficulty, celebration intensity, and messaging tone, based on an 8-dimensional psychology profile.

Core Innovation: Psychology-driven personalization engine adapting to individual user behavior

Monetization: Freemium model via RevenueCat (Free/Pro tiers)

Technology Stack

Frontend

  • Framework: Flutter (cross-platform iOS/Android)
  • State Management: Riverpod (reactive, type-safe)
  • Navigation: GoRouter (auth-aware)
  • HTTP: Dio (auto token-refresh)
  • Storage: Secure keychain/keystore + local preferences
  • Payments: RevenueCat SDK
  • Notifications: Firebase Cloud Messaging
  • UI: Material 3 with custom animations

Backend

  • Framework: FastAPI (async Python)
  • Database: MongoDB (document-oriented)
  • Cache: Redis (task lookup, rate limits)
  • AI: Large language models
  • Auth: JWT with refresh tokens
  • Notifications: Firebase Admin SDK
  • Payments: RevenueCat HTTP API + webhooks

Infrastructure

  • Hosting: Google Cloud Run (serverless)
  • Database: MongoDB Atlas (managed)
  • Cache: Redis Cloud (managed)
  • CI/CD: GitHub Actions
  • Registry: Google Artifact Registry

System Architecture

flowchart TB A["Mobile App"] B["Backend API"] C["MongoDB Atlas"] D["Redis Cache"] E["Firebase FCM"] A -->|REST HTTPS| B B --> C B --> D B --> E

Personalization Engine

1. Psychology Profiling

Free Users: Select 1 of 6 personas (explorer, perfectionist, people_pleaser, overthinker, sprinter, dreamer)

Pro Users: Complete 8-dimension quiz:

  • Growth vs. Fixed Mindset: Affects praise style
  • Confidence: Determines task difficulty
  • Rumination Tendency: Task complexity and framing
  • Shame Sensitivity: Language softening
  • Stimulation Tolerance: Celebration intensity
  • Attachment Style: Notification frequency and reassurance
  • Preferred Pace: Task volume and spacing
  • Recovery Pattern: Comeback vs. rest routing

Profile stored in MongoDB; cached in Redis for fast personalization.

2. Usage Tracking and Optimal Timing

Tracking:

  1. Each task completion records timestamp
  2. Backend analyzes 14-30 day window
  3. Identifies peak completion hours
  4. Calculates optimal engagement hour

Decision Logic:

  • 14+ completions -> Use historical optimal hour
  • New users -> Persona-based heuristic (e.g., sprinters at 6am)
  • Cached in Redis for fast lookup

Notification Timing:

  • Scheduler runs every 60 seconds
  • Sends within plus/minus 10 min of optimal hour, or 2-hour catch-up window

3. Language Adaptation

All messaging adapts based on psychology profile:

  • Shame sensitivity -> Tone adjustment (softer or direct)
  • Confidence level -> Process-focused vs. outcome-focused
  • Rumination tendency -> Action-oriented vs. reflective
  • Stimulation tolerance -> Celebration and animation intensity
  • Attachment style -> Notification frequency and reassurance density
  • Preferred pace -> Message tempo and complexity

Messages validated against non-violent communication principles.

4. Task Difficulty Adaptation

Adjustments:

  • Completion rate 80%+ -> +15% difficulty
  • Completion rate less than or equal to 40% -> -15% difficulty
  • Rest energy phase -> -10% difficulty
  • Peak energy phase -> +10% difficulty
  • High rumination -> Lower task complexity

Example: User with 85% completion rate, high rumination, in rest phase receives tasks 3 difficulty points lower with simplified instructions.

Notification System

Decision Flow

flowchart TD A["Every 60s"] --> B["For each user"] B --> C["Resolve timezone"] C --> D["Get optimal hour"] D --> E{"In send window?"} E -->|Yes| F["Pick top task"] E -->|No| Z["Skip cycle"] F --> G{"User tier"} G -->|Pro| H["AI body"] G -->|Free| I["Template + modifiers"] H --> J["Phrase validation"] I --> J J --> K["Send FCM"] K --> L["Log event"]

Same task definition receives different messaging based on user psychology: tone, complexity, and motivational framing all adapt.

RevenueCat Integration

Tiers

Free: 3 goals, persona selection, template notifications, basic analytics

Pro ($6.99/month): Unlimited goals, 8-dimension quiz, AI notifications, weekly insights, advanced analytics

Implementation

Client:

  • SDK initialized on launch
  • User ID linked to RevenueCat
  • Check isPro() before feature access
  • Present native paywall (iOS/Google Play)

Backend:

  • Webhook receives subscription events
  • Validates X-Revenuecat-Secret header
  • Updates subscription_tier in MongoDB
  • Pro endpoints return 402 (Payment Required) for free users
  • /billing/refresh syncs subscription status

Revenue Model: $6.99/mo x 15-20% conversion = $16.8K-$50.3K Year 1 ARR (200-600 paying users)

Core Algorithms

Streak Calculation

Count backwards from today. Each day with 1+ completed task adds to streak. First gap stops count. (Example: Mon-Thu completed, Fri missed = 4-day streak)

Milestone Progress

For each milestone: progress = completed_tasks / total_tasks. At 100%, celebrate.

Task Priority

Sort by: Status (pending > completed) -> Priority field (0-3) -> Difficulty (easier first)

Deployment

Backend

  • Docker image built from FastAPI app
  • Pushed to Google Artifact Registry
  • Deployed to Cloud Run (serverless, auto-scaling)
  • Environment variables: MongoDB URI, Redis URL, API keys
  • Zero-downtime rolling updates

Database

  • MongoDB Atlas (cloud-managed, auto-scaling, geo-redundant)
  • Indexes on user_id, created_at, status

Cache

  • Redis Cloud (optimal engagement times, task suggestions, rate limits)
  • 24-hour TTL on most keys

CI/CD

GitHub Actions workflow:

  1. Push to main
  2. Run tests
  3. Build + push Docker image
  4. Deploy to Cloud Run
  5. Smoke tests
  6. Auto-rollback on failure

Result: Code to production in 5-10 minutes.

Security

Authentication

  1. User signs up/logs in
  2. Backend generates JWT tokens:
    • access_token (15 min, in Authorization header)
    • refresh_token (7 days, secure storage)
  3. Access token in RAM; refresh token in Keychain/Keystore
  4. On 401, client calls /auth/refresh -> new access token -> retry (seamless)
  5. On logout, clear tokens and revoke FCM token

OAuth

  • Google: Verify via google-auth library
  • Apple: Fetch JWKS, verify signature
  • Token exchange server-side only

Data Protection

  • Passwords: Argon2 hashing
  • In transit: HTTPS only
  • At rest: MongoDB Atlas encryption
  • No logging of passwords, tokens, or personal data

Architectural Decisions

Why Riverpod? Type-safe state with built-in caching and dependency injection.

Why MongoDB? Flexible schema for evolving psychology profiles. Nested documents match our data model. Horizontal scaling via sharding.

Why Async? FastAPI handles thousands of concurrent users. Notification scheduler runs without blocking. I/O operations do not block requests. Cost-effective on serverless.

Why Cloud Run? No infrastructure management. Auto-scales 0 to thousands. Pay per request. Automatic deployments. Easy rollback.

Conclusion

Sparcd's architecture prioritizes personalization at scale. The psychology engine continuously adapts task difficulty, notification timing, and language based on individual profiles. RevenueCat enables sustainable monetization with clear Free/Pro separation. The cloud-native backend ensures reliability and scalability without infrastructure overhead.

The system is production-ready with comprehensive error handling, secure authentication, and monitoring for observability.