Cullo App is a high-performance, enterprise-grade subscription tracking and management platform designed to help users stop wasting money on forgotten services. It moves beyond simple "reminder notifications" by offering deep financial insights and a cascading alert system.
- Subscription Lifecycle Management: Express-entry for services (Netflix, Spotify, etc.) with granular billing cycles.
- Cascading renewal Alerts: A sophisticated notification engine that handles system defaults and user-specific overrides from minutes to months in advance.
- Bill Shock Protection: Real-time monitoring of upcoming renewals against user-set monthly financial limits.
- Monthly Spend Dashboard: Comprehensive visual breakdown of total costs, category spending, and expensive outliers.
- Inactive Subscription Detector: Intelligent tracking of "last used" status to identify potential savings.
- Family Sharing (PRO): Collaborative dashboards for household subscription management.
- Cross-Platform Sync (PRO): Secure cloud backup and synchronization across devices.
This project is built with a focus on scalability, maintainability, and high standards:
- Backend: Laravel 13 (PHP 8.3+)
- Storage: PostgreSQL optimized for relational consistency
- Auth: Laravel Sanctum (token-based mobile authentication)
- Real-time: Laravel Reverb (WebSocket server for push notifications)
- Background Jobs: Laravel Queue (
databasedriver) with automatic retries - Security: UUID-based primary keys for all entities to prevent ID enumeration
- Scalability: Domain-driven controller namespacing (
Api\Auth,Api\Core,Api\Subscription,Api\Dashboard)
Detailed documentation for the backend development can be found in the docs directory:
- Data Model & Schema: Comprehensive ERD and table definitions.
- Features Roadmap: Full business-to-API mapping across all development phases.
- PHP 8.3+
- Composer
- Node.js & NPM
-
Clone the repository
git clone [repository-url] cd cullob -
Run the setup script The project includes a comprehensive setup script defined in
composer.json:composer run setup
-
Configure your environment Copy
.env.exampleto.envand update your database, Reverb, and broadcasting credentials:cp .env.example .env php artisan key:generate
The Cullo backend requires four processes to be running simultaneously for full functionality. Open four terminal tabs and run each:
php artisan serveHandles all push notifications delivered to mobile clients in real-time.
php artisan reverb:startOn production or staging, run Reverb in the background:
php artisan reverb:start --host="0.0.0.0" --port=8080 --daemon
Processes the DeliverRenewalAlertJob dispatched by the alert scanner. Required for notifications to be actually sent.
php artisan queue:workTo process a single job for quick debugging:
php artisan queue:work --once
In production this is a single cron entry. For local development, run the scheduler in watch mode:
php artisan schedule:workThe scheduler runs
alerts:processdaily at midnight to scan subscriptions and dispatch renewal alert jobs.
# Manually trigger the renewal alerts scanner at any time
php artisan alerts:process
# View pending jobs sitting in the queue
php artisan queue:monitor default
# Retry failed jobs
php artisan queue:retry all
# Inspect failed jobs
php artisan queue:failed# Generate a Pesapal checkout URL specifically to test MTN Mobile Money and even other payments like Airtel Money, Card payments and even pespal wallet!!
php artisan cullo:test-mtnAll protected endpoints require a Bearer token obtained from:
POST /api/auth/login
Pass the token in the Authorization header:
Authorization: Bearer {token}
Cullo App follows strict security standards. If you discover a vulnerability, please follow enterprise disclosure protocols or contact the lead developer.
This project is open-sourced software licensed under the MIT license.