Skip to content
BranchesTags

Repository files navigation

🏠 Beulah Platform

West Africa's Premier Home Services Platform - Connecting homeowners with trusted service providers across Ghana and Nigeria.

Build Status License Flutter Node.js Docker

🌟 Overview

Beulah is a comprehensive home services platform designed specifically for the West African market. We connect homeowners with verified service providers for cleaning, repairs, maintenance, and specialized services across major cities in Ghana and Nigeria.

🎯 Mission

To make quality home services accessible, reliable, and affordable for every Ghanaian and Nigerian household while empowering local service providers with technology and opportunities.

🌟 Overview

Beulah LLC is a modern, scalable service marketplace platform designed specifically for the Ghanaian and Nigerian market. Our platform connects customers seeking various services with verified, professional service providers, ensuring quality, reliability, and convenience.

🛠️ Project Structure

Beulah/
├── customer_app/              # Flutter app for customers
│   ├── lib/                   # Application source code
│   ├── assets/                # Images, fonts, animations
│   ├── test/                  # Unit and widget tests
│   └── pubspec.yaml           # Dependencies and configuration
├── provider_app/              # Flutter app for service providers
│   ├── lib/                   # Application source code
│   ├── assets/                # Images, fonts, animations
│   ├── test/                  # Unit and widget tests
│   └── pubspec.yaml           # Dependencies and configuration
├── admin_dashboard/           # Web/Flutter Admin dashboard
│   ├── lib/                   # Dashboard source code
│   ├── web/                   # Web-specific files
│   ├── assets/                # Static assets
│   └── pubspec.yaml           # Dependencies and configuration
├── backend/                   # Backend services & APIs
│   ├── src/                   # Source code
│   ├── tests/                 # API tests
│   ├── docs/                  # API documentation
│   ├── config/                # Configuration files
│   ├── migrations/            # Database migrations
│   ├── package.json           # Node.js dependencies
│   └── Dockerfile             # Container configuration
├── shared/                    # Shared utilities and models
│   ├── lib/                   # Shared library code
│   ├── test/                  # Library tests
│   ├── pubspec.yaml           # Library dependencies
│   └── README.md              # Library documentation
├── docs/                      # Documentation and specifications
│   ├── api/                   # API documentation
│   ├── architecture/          # System architecture docs
│   ├── mobile/                # Mobile app documentation
│   ├── web/                   # Web dashboard documentation
│   ├── development/           # Development guides
│   ├── business/              # Business logic documentation
│   ├── integration/           # Integration guides
│   ├── operations/            # Operations and deployment
│   └── README.md              # Documentation index
└── README.md                  # This file

🚀 Key Features

For Customers

  • 🔍 Smart Service Discovery: AI-powered search and filtering with real-time availability powered by Supabase's PostgreSQL database
  • 👤 Comprehensive Provider Profiles: Detailed provider information with verified credentials, portfolios, ratings, and real-time reviews stored in Supabase
  • ⚡ Real-time Booking System: Instant booking with live availability checking, calendar synchronization, and automatic confirmations via Supabase real-time subscriptions
  • 📍 Live Service Tracking: GPS-based real-time tracking of service providers with push notifications via Firebase Cloud Messaging
  • 💳 Secure Payment Gateway: Multiple payment options (Paystack/Flutterwave) with escrow protection and transaction history stored securely in Supabase
  • ⭐ Advanced Review System: Rate and review completed services with photo uploads, stored in Supabase with real-time updates
  • 💬 Real-time Chat Support: Direct messaging with providers using Supabase real-time features and Firebase push notifications
  • 🛡️ Smart Dispute Resolution: AI-assisted dispute handling system with escalation workflows and resolution tracking
  • 🔔 Intelligent Notifications: Firebase-powered push notifications for booking updates, provider messages, and promotional offers
  • 📊 Personal Analytics: Service history, spending analytics, and personalized recommendations powered by Firebase Analytics
  • 🌐 Offline Capability: Cached data and offline booking queue with automatic sync when connection is restored
  • 🔐 Secure Authentication: Firebase Authentication with multi-factor authentication, social login, and biometric security

For Service Providers

  • Profile Management: Comprehensive business profile setup
  • Job Management: Accept, schedule, and track jobs
  • Earnings Dashboard: Real-time earnings and analytics
  • Customer Communication: Direct chat with customers
  • Document Management: Upload certifications and portfolios
  • Calendar Integration: Sync with personal calendars
  • Performance Analytics: Track ratings and performance metrics
  • Payment Tracking: Monitor payments and withdrawals

For Administrators

  • User Management: Manage customers and providers
  • Service Categories: Configure available services
  • Analytics Dashboard: Comprehensive platform analytics
  • Payment Management: Handle transactions and disputes
  • Content Moderation: Review and moderate content
  • System Configuration: Platform settings and features
  • Report Generation: Generate various business reports
  • Notification Management: Send platform-wide notifications

🛡️ Technology Stack

Frontend

  • Flutter: Cross-platform mobile and web development
  • Dart: Programming language
  • GetX: State management
  • Go Router: Navigation and routing
  • Material Design 3: UI/UX framework

Backend

  • Supabase (PostgreSQL): Primary database with real-time capabilities
  • Redis: Caching and session management
  • Socket.io: Real-time communication
  • JWT: Authentication and authorization

Cloud Services

  • Firebase: Authentication, push notifications, analytics
  • Cloudinary: Image and video management
  • AWS S3: File storage
  • Google Maps: Location services
  • Paystack/Flutterwave: Payment processing

DevOps & Tools

  • Docker: Containerization
  • GitHub Actions: CI/CD pipeline
  • ESLint/Prettier: Code formatting
  • Jest: Testing framework
  • Swagger: API documentation

🏗️ Architecture

System Architecture

  • Microservices: Modular backend services
  • RESTful APIs: Standard HTTP APIs
  • Real-time Communication: WebSocket connections
  • Event-driven: Asynchronous event processing
  • Scalable: Horizontal scaling capabilities

Security Features

  • End-to-end Encryption: Secure data transmission with TLS 1.3
  • Multi-layered Authentication: Firebase Auth + Supabase RLS for granular access control
  • API Protection: Rate limiting, request validation, and DDoS protection
  • Data Sanitization: Input validation and SQL injection prevention
  • Compliance: GDPR, CCPA, and local data protection regulations
  • Audit Logging: Comprehensive activity tracking in Supabase
  • Secure File Handling: Virus scanning and content validation for uploads

🔧 Technical Integration

Supabase + Firebase Synergy

  • Authentication Flow: Firebase handles user authentication while Supabase manages user profiles and permissions
  • Real-time Data: Supabase real-time subscriptions for live booking updates, chat messages, and provider locations
  • Offline-First Architecture: Local Supabase caching with Firebase for push notifications when back online
  • Analytics Pipeline: Firebase Analytics feeds into Supabase for comprehensive business intelligence
  • File Management: Supabase Storage for user files with Firebase for metadata and access control
  • Push Notifications: Firebase Cloud Messaging triggered by Supabase database events
  • Edge Computing: Supabase Edge Functions for serverless business logic with Firebase for monitoring

Data Architecture

  • Primary Database: Supabase PostgreSQL for transactional data
  • Real-time Layer: Supabase subscriptions for live updates
  • Analytics Store: Firebase Analytics for user behavior insights
  • File Storage: Supabase Storage with automatic CDN distribution
  • Cache Layer: Redis for session management and frequently accessed data
  • Search Engine: Full-text search capabilities with Supabase and external search services

🚀 Quick Start

Prerequisites

  • Flutter SDK (>=3.16.0)
  • Redis (>=6.0)
  • Docker & Docker Compose
  • Git

Installation

  1. Clone the repository

    git clone https://github.com/beulah-llc/beulah-platform.git
cd beulah-platform

  2. Setup Backend

    cd backend
npm install
cp .env.example .env
# Configure environment variables
npm run dev

  3. Setup Shared Library

    cd ../shared
flutter pub get
flutter test

  4. Setup Customer App

    cd ../customer_app
flutter pub get
flutter run

  5. Setup Provider App

    cd ../provider_app
flutter pub get
flutter run

  6. Setup Admin Dashboard

    cd ../admin_dashboard
flutter pub get
flutter run -d chrome

📱 Platform Components

Customer Mobile App

  • Native Performance: Flutter-powered iOS and Android apps with platform-specific optimizations
  • Seamless Booking Flow: Intuitive multi-step booking process with real-time validation via Supabase
  • Real-time Features: Live notifications, chat, and booking updates powered by Firebase Cloud Messaging and Supabase real-time subscriptions
  • Smart Offline Mode: Intelligent caching with Supabase local storage and automatic sync when online
  • Localization: Multi-language support for West African languages with Firebase Remote Config
  • Analytics Integration: User behavior tracking and crash reporting via Firebase Analytics and Crashlytics
  • Secure Data: End-to-end encryption for sensitive data with Firebase Security Rules and Supabase RLS (Row Level Security)

Provider Mobile App

  • Job management interface
  • Earnings tracking
  • Customer communication
  • Document upload
  • Performance analytics

Admin Web Dashboard

  • Comprehensive management interface
  • Real-time analytics
  • User management
  • Content moderation
  • System configuration

Backend Services

  • Authentication & Authorization: Firebase Authentication with custom claims and Supabase Row Level Security (RLS)
  • Real-time Database: Supabase PostgreSQL with real-time subscriptions for live updates
  • Booking Management: Complex booking workflows with state management in Supabase
  • Payment Processing: Secure payment handling with Paystack/Flutterwave integration and transaction logging
  • Notification Engine: Firebase Cloud Messaging for push notifications with targeting and analytics
  • File Storage: Supabase Storage for user uploads with CDN delivery and automatic optimization
  • Analytics & Monitoring: Firebase Analytics for user insights and Crashlytics for error tracking
  • API Gateway: RESTful APIs with Supabase Edge Functions for serverless computing
  • Real-time Communication: WebSocket connections via Supabase for live chat and updates

🌍 Localization

Supported Languages

  • English (Primary - Ghana & Nigeria)
  • Twi (Ghana)
  • Ga (Ghana)
  • Ewe (Ghana)
  • Hausa (Northern Nigeria & Northern Ghana)
  • Yoruba (Western Nigeria)
  • Igbo (Eastern Nigeria)
  • Pidgin English (Widely spoken)

Supported Regions

Ghana 🇬🇭

  • Greater Accra Region 🏙️
  • Ashanti Region 👑
  • Western Region 🛢️
  • Central Region 🏖️
  • Eastern Region 🌿

Nigeria 🇳🇬

  • Lagos State 🏙️
  • Abuja (FCT) 🏛️
  • Kano State 🕌
  • Rivers State 🛢️
  • Oyo State 👑
  • Kaduna State ⚡

Currency and Payments

Ghana 🇬🇭

  • Primary Currency: Ghanaian Cedi (GH₵)
  • Payment Methods:
    • Bank transfers
    • Debit/Credit cards
    • Mobile money (MTN Mobile Money, AirtelTigo Money, Vodafone Cash)
    • USSD payments
    • Cash on delivery

Nigeria 🇳🇬

  • Primary Currency: Nigerian Naira (₦)
  • Payment Methods:
    • Bank transfers
    • Debit/Credit cards
    • Mobile money (MTN, Airtel, etc.)
    • USSD payments
    • Cash on delivery

🔧 Development

Code Style

  • Follow Dart/Flutter conventions
  • Use ESLint for JavaScript
  • Implement comprehensive testing
  • Document all APIs
  • Follow Git flow branching

Testing Strategy

  • Unit tests for business logic
  • Widget tests for UI components
  • Integration tests for workflows
  • API tests for backend services
  • End-to-end testing

Deployment

  • Staging environment for testing
  • Production deployment via CI/CD
  • Blue-green deployment strategy
  • Automated rollback capabilities
  • Performance monitoring

📊 Business Model

Revenue Streams

  • Commission: Percentage from completed bookings
  • Subscription: Premium provider memberships
  • Advertising: Featured listings and promotions
  • Value-added Services: Insurance, financing, training

Target Market

  • Primary: Urban areas in Ghana and Nigeria
  • Secondary: Suburban and rural expansion
  • Demographics: Middle-class households and businesses
  • Services: Home improvement, maintenance, professional services

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new features
  5. Ensure all tests pass
  6. Submit a pull request

Development Guidelines

  • Follow coding standards
  • Write comprehensive tests
  • Update documentation
  • Use meaningful commit messages
  • Review code thoroughly

📄 License

This project is licensed under the MIT License with additional terms for Beulah LLC. See the LICENSE file for details.

📞 Support

Ghana Office 🇬🇭

Nigeria Office 🇳🇬

Documentation

🙏 Acknowledgments

  • Flutter team for the amazing framework
  • Open source community for valuable packages
  • Ghanaian and Nigerian tech ecosystems for inspiration
  • Beta testers and early adopters

Made with ❤️ in West Africa 🇬🇭🇳🇬

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages