🛡️ Cullo — Subscription Intelligence, Redefined

Guard your wallet. Own your subscriptions.

Cullo is a premium subscription tracking mobile app built with React Native + Expo. It gives users a beautiful, intelligent dashboard to track, manage, and optimize their recurring bills — before they silently drain the wallet.

---

✨ Features

📊 Live Dashboard

• Interactive SVG Trend Chart — touch-drag to reveal exact monthly spend at any point in time
• Monthly & Yearly Totals — normalized across weekly, monthly, and yearly billing cycles
• Upcoming Renewals — bills due in the next 7 days surfaced front and center
• Top Subscriptions — ranked by monthly cost impact

💳 Subscription Management

• Add bills in seconds with 10-Second Popular Service Setup (Netflix, Spotify, Adobe, etc.)
• Full details view: amount, billing cycle, renewal date, category, active status
• Mark as Paid, Pause / Resume Tracking, and Delete — all with haptic feedback
• Custom branded icons for popular services with smart fallbacks

🔔 Global Toast Notifications

• Context-aware success, info, and error toasts on every action
• Example: "Spotify marked as paid!", "Adobe Creative Cloud deleted"
• Smooth slide-in/out animations — no ugly system dialogs

🔒 Cullo Pro Paywall

• Free tier capped at 3 tracked subscriptions
• Aggressive glassmorphism paywall with expo-blur frosted overlay
• Triggers on tab focus using useFocusEffect — no bypass possible
• "Not Now" safely redirects to the dashboard

🗑️ Reusable Confirm Modal

• CulloConfirmModal — a premium blurred confirmation dialog
• Used for destructive delete actions; fully reusable across the app
• Supports destructive mode (red CTA), loading state, and custom messaging

🔐 Authentication

• JWT-based login & registration
• Multi-Factor Authentication (MFA) via OTP
• Forgot password / reset flow
• Secure token storage with expo-secure-store

🎨 Premium Design System

• Custom CulloText, CulloButton, CulloInput, CulloNotification components
• Floating pill tab bar with deep indigo branding (#1E1B4B)
• Glassmorphism modals using expo-blur
• Haptic feedback on every meaningful interaction via expo-haptics
• Google Fonts via expo-font

---

🏗️ Tech Stack

Layer	Technology
Framework	React Native 0.81 + Expo SDK 54
Routing	Expo Router (file-based)
Charts	react-native-svg + d3-shape
Animations	react-native-reanimated + React Native Animated API
Blur Effects	expo-blur
Haptics	expo-haptics
Secure Storage	expo-secure-store
Image Handling	expo-image
Date Picker	@react-native-community/datetimepicker
Language	TypeScript 5.9

---

📁 Project Structure

cullof/
├── app/
│   ├── (auth)/          # Login, Register, MFA, Forgot Password flows
│   ├── (onboarding)/    # Welcome & selection onboarding screens
│   ├── (tabs)/          # Main tab screens: Dashboard, Explore, Add, Favorites, Profile
│   └── subscription/    # Subscription detail screen [id].tsx
│
├── src/
│   ├── features/
│   │   └── auth/        # Auth screens & logic
│   └── shared/
│       ├── api/         # API client & secure storage
│       ├── components/  # Design system components
│       ├── context/     # AuthContext, NotificationContext
│       └── theme/       # Colors, typography tokens
│
├── assets/              # Fonts, images, icons
└── docs/                # Integration guides & plans

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• EAS CLI (npm install -g eas-cli)
• Android Studio & SDK (Required for local Android builds)
• Java Development Kit (JDK) 17+ (Required for local Android builds)
• Xcode (Required for local iOS builds)
• iOS Simulator or Android Emulator, or a physical device with Development Client

⚠️ Local Build Setup

If you are running --local builds, ensure your environment variables are configured in your shell profile (.zshrc or .bash_profile):

# Android Example
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

🛠️ Developer Commands

Scope	Command	Description
Local	npx expo start	Start development server (for Expo Go)
Local	npx expo run:android	Build and run Development Client on Android
Local	npx expo run:ios	Build and run Development Client on iOS
EAS	eas build -p android --profile preview	Build APK for testing on physical devices
Local EAS	npx eas-cli build --platform android --local --profile preview	Build APK locally for Android (Requires Android Studio & JDK)
EAS	eas build -p android --profile development	Build Development Client APK for cloud staging
EAS	eas build -p ios --profile preview	Build iOS Internal Distribution binary
Update	eas update --branch production	Instantly push JS changes to all installs

---

🐘 Backend Commands

To keep Cullo's intelligence running, ensure the backend is healthy:

# In the /cullob directory:
php artisan migrate         # Sync database schema
php artisan serve           # Start the local API server
php artisan queue:work      # CRITICAL: Processes push notifications

---

🔗 Backend

Cullo's frontend connects to a Laravel 11 + PostgreSQL REST API (cullob).

Key API endpoints used:

Endpoint	Method	Purpose
/auth/login	POST	Authenticate user
/auth/register	POST	Create account
/subscriptions	GET / POST	List & create subscriptions
/subscriptions/{id}	GET / DELETE	Fetch & delete a subscription
/subscriptions/{id}/mark-paid	POST	Mark subscription as paid
/subscriptions/{id}/toggle-inactivity	POST	Pause / Resume tracking
/dashboard/metrics	GET	Aggregated dashboard data
/categories	GET	Subscription categories
/services/popular	GET	Popular service presets

---

🎯 Cullo Pro

The free tier allows tracking up to 3 subscriptions. Cullo Pro unlocks:

• ♾️ Unlimited subscription tracking
• 🐕 Guard Dog renewal alerts (push notifications)
• 👨‍👩‍👧 Advanced family sharing
• 📈 Extended historical trends

---

📸 Screens

Screen	Description
Dashboard	Live spend chart, upcoming renewals, top subscriptions
Add Bill	Quick-add with popular service chips + full manual form
Subscription Detail	View, pause, mark paid, or delete a subscription
Explore / Stats	Spending analytics and category breakdown
Profile	Account settings and Pro upgrade

---

🧑‍💻 Development Notes

• The monthly_trend chart is subscription-derived (projected cost), not payment-history-dependent — so it always shows meaningful data from day one
• The Pro paywall uses useFocusEffect so it re-evaluates the limit every time the tab is focused — no bypass via tab switching
• CulloConfirmModal and CulloNotification are fully reusable across any screen

---

📄 License

Private & proprietary. All rights reserved © 2026 Cullo.