Full-Stack Digital Mental Health & Wellness Platform
Ezzy Freedom & Hope is a production-ready digital platform built with Next.js 16 for a mental health and addiction recovery practice. It enables users to purchase ebooks and research articles, read content securely via an in-browser PDF reader, book counseling appointments, and access a personal digital library, all supported by secure M-Pesa STK Push payments. To safeguard intellectual property, content is stored on Cloudflare R2 and streamed exclusively to authenticated users through a secure server-side proxy featuring per-user watermarking and rate limiting.
Objectives
The primary goals of the project were to:
Digitize a traditional counseling practice
Securely distribute premium digital publications
Integrate Kenya's M-Pesa payment ecosystem
Provide a seamless online reading experience
Build a scalable administration system
Protect copyrighted digital content
Deliver an intuitive user experience across desktop and mobile devices
Key Features
Client Portal
Users can:
Register and authenticate using email or Google
Browse books, articles, and counseling services
Purchase digital content through M-Pesa STK Push
Read purchased ebooks in a secure browser-based reader
Download purchased research articles
Track their reading progress
Create bookmarks
Schedule therapy appointments
Manage their digital library
Reset passwords through email
Administration Portal
Administrators can:
Manage books
Manage research articles
Manage counseling services
Publish blog posts
Review appointments
Monitor payment transactions
Track platform statistics
Upload digital assets directly to Cloudflare R2
Manage users and platform content
Technology Stack
Frontend
Next.js 16
React 19
TypeScript
Tailwind CSS
shadcn/ui
Radix UI
Backend
Next.js Server Components
Server Actions
API Routes
Prisma ORM
PostgreSQL
Authentication
Better Auth
Google OAuth
Session-based authentication
Cloud Infrastructure
Cloudflare R2
Vercel
Resend Email
Payments
Safaricom Daraja API
M-Pesa STK Push
PDF Reader
PDF.js
React PageFlip
Architecture Highlights
Secure Digital Content Delivery
One of the biggest engineering challenges was protecting premium ebooks from unauthorized sharing while maintaining a smooth reading experience.
Instead of exposing storage URLs directly to users, the application streams PDF files through a secure server-side proxy. Every request validates the authenticated session, verifies ownership of the purchased content, and supports HTTP Range Requests for efficient page loading.
Additional protection mechanisms include:
Per-user watermarking
Short-lived signed URLs
Request rate limiting
Purchase verification
Disabled public storage access
M-Pesa Payment Integration
The payment workflow was designed around Safaricom's asynchronous callback architecture.
Each purchase creates a pending transaction before initiating an STK Push request. Once payment is completed, the callback updates the transaction and grants permanent library access through an idempotent database operation, preventing duplicate purchases caused by repeated callbacks.
Browser-Based Ebook Reader
Rather than relying on third-party ebook platforms, a custom reader was developed using PDF.js.
Features include:
Progressive page loading
Full-text search
Reading progress synchronization
Bookmarks
Responsive page layouts
Dark mode
Fullscreen support
Mobile swipe navigation
Animated page turning
Cloud Storage Strategy
Cloudflare R2 was selected instead of Amazon S3 because of its zero-egress pricing model, making it significantly more cost-effective for frequently accessed PDF content.
The upload workflow uses presigned URLs, allowing administrators to upload files directly to cloud storage without routing large files through the application server.
Security Considerations
Security was a major design priority throughout the application.
Implemented protections include:
Role-Based Access Control (RBAC)
Database-backed authentication sessions
Protected server-side routes
Purchase validation
Secure file proxying
Rate limiting
Per-user PDF watermarking
Environment-based secret management
Idempotent payment processing
Signed upload and download URLs
Database Design
The application models several interconnected business domains, including:
Users
Authentication Sessions
OAuth Accounts
Books
Articles
Purchases
Transactions
Reading Progress
Bookmarks
Appointments
Services
Blog Posts
The schema was designed to support future platform growth while maintaining data consistency through relational integrity.
Challenges & Engineering Solutions
Secure PDF Distribution
Challenge
Protect premium ebooks without sacrificing performance.
Solution
Implemented a secure streaming proxy with authenticated range requests and watermarking.
Reliable Mobile Payments
Challenge
Safaricom callbacks can be delivered multiple times.
Solution
Used idempotent database operations to guarantee purchase consistency.
Efficient Reading Experience
Challenge
Large PDF files can negatively impact performance.
Solution
Implemented incremental page loading using HTTP Range Requests and PDF.js.
Cloud Storage Costs
Challenge
Minimize bandwidth costs for frequently accessed files.
Solution
Selected Cloudflare R2 due to its zero-egress pricing model.
Outcomes
The completed platform successfully delivers:
Secure digital content distribution
Integrated mobile payments
Online appointment management
Production-ready authentication
Protected ebook streaming
Responsive administration dashboard
Modern user experience
Scalable architecture suitable for future feature expansion
Skills Demonstrated
This project showcases expertise in:
Full-Stack Development
Software Architecture
Secure Content Delivery
Authentication & Authorization
Payment Gateway Integration
Cloud Storage
Database Design
REST API Development
Server Components
Performance Optimization
Security Best Practices
UI/UX Engineering
Project Summary
Ezzy Freedom & Hope demonstrates the development of a production-ready healthcare platform that combines secure digital publishing, online counseling services, and mobile payment integration into a cohesive ecosystem. The project highlights strong full-stack engineering practices, thoughtful system architecture, and practical solutions to real-world challenges such as secure content delivery, payment reliability, and scalable cloud infrastructure.