Skip to content

Architecture

High-Level Architecture

graph TB
    subgraph "Client Tier"
        M["Flutter Mobile App<br/>Dart 3.x / Riverpod"]
        AW["Admin Web App<br/>React 18 / MUI 5 / Redux"]
        SW["Seller Web App<br/>React 18 / MUI 5 / Redux"]
    end

    subgraph "Backend Tier"
        SAPI["Supabase API<br/>PostgREST + Auth + Realtime"]
        PG[("PostgreSQL 15<br/>32 tables + views + functions")]
        SS["Supabase Storage<br/>Images, Documents"]
        SF["Supabase Edge Functions<br/>Deno (coming soon)"]
    end

    subgraph "External"
        CH["Chapa Payment Gateway<br/>Ethiopian Payments"]
        FCM["Firebase Cloud Messaging<br/>Push Notifications"]
        CL["Cloudinary<br/>Chat Image Hosting"]
    end

    M --> SAPI
    AW --> SAPI
    SW --> SAPI
    SAPI --> PG
    M --> SS
    AW --> SS
    SW --> SS
    M --> CH
    M --> FCM
    M --> CL

Flutter App Architecture

pharmanet/
├── lib/
│   ├── main.dart                    # App entry, providers, routing
│   ├── firebase_options.dart        # Firebase config
│   ├── core/                        # Shared layer
│   │   ├── api/                     # 20 API classes (Supabase client wrappers)
│   │   ├── config/                  # App & payment config
│   │   ├── constants/               # Colors, strings, constants
│   │   ├── enums/                   # UserRole enum
│   │   ├── models/                  # 14 freezed data models
│   │   ├── providers/               # 25 Riverpod providers
│   │   ├── routes/                  # Named route definitions
│   │   ├── services/                # 12 service classes
│   │   ├── theme/                   # AppTheme with light/dark
│   │   └── utils/                   # Helpers, validators, logger
│   ├── features/                    # Feature modules
│   │   ├── auth/                    # Login, register, OTP
│   │   ├── cart/                    # Cart, checkout
│   │   ├── onboarding/              # Welcome screens
│   │   ├── orders/                  # Order list, detail, tracking
│   │   ├── pharmacist/              # Seller dashboard, products, orders
│   │   ├── pharmacy/                # Catalog, detail, map
│   │   ├── profile/                 # Profile, settings, addresses, security
│   │   └── public/                  # Home, notifications, wishlist
│   ├── widgets/                     # Reusable widgets
│   │   ├── cart/                    # Cart summary
│   │   ├── home/                    # Nearby pharmacies
│   │   └── shared/                  # 18 shared widgets
│   └── l10n/                        # English + Amharic locales

React Web App Architecture

pharmanet-{admin,web}/
├── src/
│   ├── main.jsx                     # Entry point
│   ├── App.jsx                      # Root with providers
│   ├── routes.jsx                   # React Router v6 config
│   ├── assets/styles/               # Global CSS + MUI theme
│   ├── components/                  # Reusable UI components
│   │   ├── common/                  # DataTable, modals, spinners
│   │   ├── layouts/                 # Header, Sidebar, MainLayout
│   │   ├── dashboard/               # Charts, stats cards
│   │   ├── products/                # Product form, list, variants
│   │   ├── orders/                  # Order list, timeline, status
│   │   ├── users/                   # User/pharmacy management
│   │   ├── payments/                # Transactions, Chapa config
│   │   ├── cms/                     # Banners, pages
│   │   ├── reports/                 # Sales, performance
│   │   └── settings/                # General, payment, email
│   ├── pages/                       # Page components (lazy-loaded)
│   ├── services/                    # 18 service modules (Supabase queries)
│   ├── store/                       # 9 Redux Toolkit slices
│   ├── hooks/                       # Custom hooks
│   ├── utils/                       # Constants, formatters, helpers
│   └── test/                        # Integration, accessibility, visual tests

Database Schema

32 tables across the following domains:

Domain Tables
Users profiles, sellers, addresses
Catalog categories, brands, products, variant_options, variant_values, variant_combinations
Commerce carts, cart_items, orders, order_items, payments, order_status_history
Engagement reviews, wishlists, chats, messages, notifications
CMS banners, static_pages, settings
Promotions promotions, offer_products
Monetization featured_product_payments, pharmacy_subscriptions, featured_product_access
Analytics analytics

Key Design Decisions

Decision Rationale
Supabase over custom backend Built-in auth, real-time, storage, and RLS reduce backend code to near zero
Riverpod over BLoC Simpler syntax, better testability, compile-time safety with code generation
Redux Toolkit over Context Predictable state management, middleware for real-time subscriptions, Redux DevTools
Freezed models Immutable data classes with JSON serialization, union types, and copy-with support
Prisma for schema Type-safe database client, auto-generated types, migration management
Chapa for payments Ethiopian market, hosted checkout reduces PCI compliance scope
MUI 5 Mature component library, responsive out of the box, customizable theme