# moussax1/oaya architecture

> Architecture diagram of the GitHub repository moussax1/oaya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moussax1/oaya
- Repository: https://github.com/moussax1/oaya

## Overview

1. **Repo shape and responsibility split**
   - This is a Flutter client app backed by Supabase, not a server-rendered app.
   - The repo is divided into three main runtime boundaries: the Flutter app in `lib/`, Supabase backend assets in `supabase/`, and native platform shells in `android/` and `ios/`.

2. **Flutter app as the primary presentation layer**
   - `lib/main.dart` bootstraps the app, and `lib/router.dart` defines navigation across auth, shopping, checkout, profile, and admin routes.
   - `lib/constants/`, `lib/widgets/`, and `lib/utils/` hold reusable UI and formatting primitives that support many screens.

3. **State management boundary**
   - State is managed with Riverpod, as noted in the README and reflected by `lib/providers/providers.dart`.
   - The app separates transient UI state from server-backed state: cart/auth/provider state in Riverpod, and data fetch/update operations delegated to services.

4. **Feature-driven screen organization**
   - `lib/screens/` is organized by user journey rather than by technical layer:
     - shopping and discovery: home, search, product detail, wishlist, cart
     - account: login, register, forgot/reset password, profile, settings
     - checkout: address selection, payment, success
     - order lifecycle: order confirmation, order history
     - admin: products, orders, users
   - This structure suggests the UI is composed around end-to-end commerce flows.

5. **Service layer as the domain/data boundary**
   - `lib/services/` contains the app’s core business integrations and data access:
     - `supabase_service.dart` initializes and wraps backend access
     - domain services for products, cart, orders, wishlist, reviews, addresses, payment methods, admin, and notifications
     - `stripe_service.dart` isolates payment-sheet behavior and payment state
     - `receipt_service.dart` and `receipt_download*` handle receipt generation/download across platforms
   - Screens should be understood as consumers of these services, not direct database clients.

6. **Backend architecture: Supabase as the system of record**
   - `supabase/migrations/` defines the database schema and RLS policies for persistent data such as profiles, products, cart items, orders, notifications, addresses, wishlist items, reviews, and payment methods.
   - The README makes clear that Row Level Security is a major architectural boundary: users can only access their own rows, while admin workflows use elevated paths and policies.

7. **Checkout and payment data flow**
   - The checkout path runs from cart to address to payment to success.
   - For Stripe payments, the Flutter app calls the Supabase edge function `create-payment-intent`, receives a `clientSecret`, and then opens the Stripe payment sheet.
   - After success, order state is persisted in Supabase, the cart is cleared, and downstream confirmation actions are triggered.
   - Cash on delivery is treated as a parallel checkout path without Stripe.

8. **Supabase Edge Functions are the backend workflow layer**
   - `supabase/functions/create-payment-intent` handles Stripe intent creation.
   - `supabase/functions/stripe-webhook` receives Stripe events and updates order/payment state.
   - `supabase/functions/send-order-email` sends order confirmation messages through Mailtrap.
   - These functions form the server-side orchestration layer for payment, fulfillment, and notification workflows.

9. **Notifications span three channels**
   - In-app feedback is handled locally by `lib/services/notification_service.dart` through SnackBars and dialogs.
   - Push notifications are powered by Firebase Cloud Messaging, with tokens stored in the backend profile data and triggered from backend events.
   - Email notifications are emitted from the Supabase edge function layer, not from the Flutter client directly.

10. **Admin capabilities are a distinct subsystem**
   - `lib/screens/admin/` and `lib/services/admin_service.dart` expose management views for users, orders, and products.
   - This is a separate role-based boundary inside the same app, backed by Supabase policies and likely elevated database permissions in the backend.

11. **Cross-platform runtime boundaries**
   - The app targets Android and iOS natively, and the README also calls out web support.
   - Android requires Firebase configuration in `android/app/`, while iOS has standard Flutter shell files in `ios/`.
   - `receipt_download_web.dart`, `receipt_download_stub.dart`, and the platform-specific receipt implementation indicate deliberate platform adaptation.

12. **Assets and branding**
   - `assets/fonts/` and theme constants in `lib/constants/theme.dart` suggest the UI design system is centralized and reused across screens.
   - The repo’s `.env` setup is app-side configuration, while secrets for Stripe, Mailtrap, and FCM are kept in Supabase secrets for backend execution.

13. **Testing architecture**
   - The repo has three test levels:
     - unit tests for cart, pricing, payment validation, and receipt formatting
     - integration tests that exercise Supabase-backed APIs for cart, orders, admin, and notification flows
     - `integration_test/e2e_test.dart` for a full user journey
   - `test_supabase_test.dart` and the README indicate that integration tests depend on real Supabase credentials, so backend connectivity is part of the test boundary.

14. **CI and delivery**
   - `.github/workflows/ci.yml` shows the project is built and validated in GitHub Actions.
   - Deployment is split: Flutter builds produce Android/web artifacts, while Supabase functions and migrations are deployed separately.
   - This is a “thin client, managed backend” architecture: the app ships UI and client logic, while data, auth, payments orchestration, and notifications live in Supabase and third-party services.

Main entry points: [`lib/router.dart`](https://github.com/moussax1/oaya/blob/main/lib/router.dart) (Router), [`lib/services`](https://github.com/moussax1/oaya/tree/main/lib/services) (Core services), [`lib/main.dart`](https://github.com/moussax1/oaya/blob/main/lib/main.dart) (Main), [`lib/widgets`](https://github.com/moussax1/oaya/tree/main/lib/widgets) (Widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_main["Main<br/>Flutter bootstrap<br/>[main.dart]"]
  node_router["Router<br/>Navigation<br/>[router.dart]"]
  node_providers["Providers<br/>Riverpod state<br/>[providers.dart]"]
  node_theme["Theme<br/>Design system<br/>[theme.dart]"]
  node_widgets["Widgets<br/>UI components"]
  node_screens_shop["Shopping<br/>Feature screens"]
  node_screens_account["Account<br/>Feature screens"]
  node_screens_checkout["Checkout<br/>Feature screens"]
  node_screens_orders["Orders<br/>Feature screens"]
  node_screens_admin["Admin UI<br/>Role-based screens"]
  node_services_core["Core services<br/>Data boundary"]
  node_stripe["Stripe client<br/>Payments"]
  node_receipt["Receipts<br/>Platform output"]
  node_supabase_service["Supabase client<br/>Backend access"]
end

subgraph group_backend["Supabase backend"]
  node_supabase_db[("Database schema<br/>SQL migrations")]
  node_fn_payment["Payment intent<br/>Edge function<br/>[index.ts]"]
  node_fn_webhook["Stripe webhook<br/>Edge function<br/>[index.ts]"]
  node_fn_email["Order email<br/>Edge function<br/>[index.ts]"]
end

subgraph group_native["Native shells"]
  node_android_shell["Android<br/>Platform shell"]
  node_ios_shell["iOS<br/>Platform shell"]
end

subgraph group_quality["Quality & delivery"]
  node_ci["CI<br/>GitHub Actions<br/>[ci.yml]"]
  node_tests["Tests<br/>Test suite"]
end

node_main -->|"bootstraps"| node_router
node_main -->|"installs"| node_providers
node_router -->|"routes to"| node_screens_shop
node_router -->|"routes to"| node_screens_account
node_router -->|"routes to"| node_screens_checkout
node_router -->|"routes to"| node_screens_orders
node_router -->|"routes to"| node_screens_admin
node_screens_shop -->|"uses"| node_widgets
node_screens_account -->|"uses"| node_widgets
node_screens_checkout -->|"uses"| node_widgets
node_screens_orders -->|"uses"| node_widgets
node_screens_shop -->|"reads data"| node_services_core
node_screens_checkout -->|"writes data"| node_services_core
node_screens_admin -->|"manages"| node_services_core
node_services_core -->|"connects via"| node_supabase_service
node_services_core -->|"delegates payments"| node_stripe
node_receipt -->|"uses"| node_services_core
node_supabase_service -->|"queries"| node_supabase_db
node_stripe -->|"requests intent"| node_fn_payment
node_fn_webhook -->|"updates state"| node_supabase_db
node_fn_email -->|"reads order data"| node_supabase_db
node_android_shell -->|"hosts"| node_main
node_ios_shell -->|"hosts"| node_main
node_ci -->|"runs"| node_tests
node_tests -->|"integration target"| node_supabase_db

click node_main "https://github.com/moussax1/oaya/blob/main/lib/main.dart"
click node_router "https://github.com/moussax1/oaya/blob/main/lib/router.dart"
click node_providers "https://github.com/moussax1/oaya/blob/main/lib/providers/providers.dart"
click node_theme "https://github.com/moussax1/oaya/blob/main/lib/constants/theme.dart"
click node_widgets "https://github.com/moussax1/oaya/tree/main/lib/widgets"
click node_screens_shop "https://github.com/moussax1/oaya/tree/main/lib/screens"
click node_screens_account "https://github.com/moussax1/oaya/tree/main/lib/screens"
click node_screens_checkout "https://github.com/moussax1/oaya/tree/main/lib/screens/checkout"
click node_screens_orders "https://github.com/moussax1/oaya/tree/main/lib/screens"
click node_screens_admin "https://github.com/moussax1/oaya/tree/main/lib/screens/admin"
click node_services_core "https://github.com/moussax1/oaya/tree/main/lib/services"
click node_stripe "https://github.com/moussax1/oaya/blob/main/lib/services/stripe_service.dart"
click node_receipt "https://github.com/moussax1/oaya/blob/main/lib/services/receipt_service.dart"
click node_supabase_service "https://github.com/moussax1/oaya/blob/main/lib/services/supabase_service.dart"
click node_supabase_db "https://github.com/moussax1/oaya/tree/main/supabase/migrations"
click node_fn_payment "https://github.com/moussax1/oaya/blob/main/supabase/functions/create-payment-intent/index.ts"
click node_fn_webhook "https://github.com/moussax1/oaya/blob/main/supabase/functions/stripe-webhook/index.ts"
click node_fn_email "https://github.com/moussax1/oaya/blob/main/supabase/functions/send-order-email/index.ts"
click node_android_shell "https://github.com/moussax1/oaya/tree/main/android/app"
click node_ios_shell "https://github.com/moussax1/oaya/tree/main/ios/Runner"
click node_ci "https://github.com/moussax1/oaya/blob/main/.github/workflows/ci.yml"
click node_tests "https://github.com/moussax1/oaya/tree/main/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_router,node_providers,node_theme,node_widgets,node_screens_shop,node_screens_account,node_screens_checkout,node_screens_orders,node_screens_admin,node_services_core,node_stripe,node_receipt,node_supabase_service toneBlue
class node_supabase_db,node_fn_payment,node_fn_webhook,node_fn_email toneAmber
class node_android_shell,node_ios_shell toneMint
class node_ci,node_tests toneRose
```

## Components

### Flutter app

Client UI, routing, state, and feature screens.

- [Main](https://github.com/moussax1/oaya/blob/main/lib/main.dart): Flutter bootstrap · App entrypoint that initializes the client shell. · `lib/main.dart`
- [Router](https://github.com/moussax1/oaya/blob/main/lib/router.dart): Navigation · Route map for auth, shopping, checkout, profile, and admin flows. · `lib/router.dart`
- [Providers](https://github.com/moussax1/oaya/blob/main/lib/providers/providers.dart): Riverpod state · Shared app state and async state wiring for the client. · `lib/providers/providers.dart`
- [Theme](https://github.com/moussax1/oaya/blob/main/lib/constants/theme.dart): Design system · Centralized colors and visual constants used across screens. · `lib/constants/theme.dart`
- [Widgets](https://github.com/moussax1/oaya/tree/main/lib/widgets): UI components · Reusable UI building blocks for product, cart, order, and loading states. · `lib/widgets`
- [Shopping](https://github.com/moussax1/oaya/tree/main/lib/screens): Feature screens · Discovery and product journey screens for home, search, details, and wishlist. · `lib/screens`
- [Account](https://github.com/moussax1/oaya/tree/main/lib/screens): Feature screens · Authentication, profile, settings, support, and notification screens. · `lib/screens`
- [Checkout](https://github.com/moussax1/oaya/tree/main/lib/screens/checkout): Feature screens · Address, payment, and success flow for completing purchases. · `lib/screens/checkout`
- [Orders](https://github.com/moussax1/oaya/tree/main/lib/screens): Feature screens · Order confirmation, history, reviews, and payment methods views. · `lib/screens`
- [Admin UI](https://github.com/moussax1/oaya/tree/main/lib/screens/admin): Role-based screens · Management screens for products, orders, and users. · `lib/screens/admin`
- [Core services](https://github.com/moussax1/oaya/tree/main/lib/services): Data boundary · Supabase access plus domain services for products, cart, orders, wishlist, reviews, addresses, and payments. · `lib/services`
- [Stripe client](https://github.com/moussax1/oaya/blob/main/lib/services/stripe_service.dart): Payments · Client-side payment-sheet integration and client secret handling. · `lib/services/stripe_service.dart`
- [Receipts](https://github.com/moussax1/oaya/blob/main/lib/services/receipt_service.dart): Platform output · Receipt generation and cross-platform download adapters. · `lib/services/receipt_service.dart`
- [Supabase client](https://github.com/moussax1/oaya/blob/main/lib/services/supabase_service.dart): Backend access · Initializes and wraps app access to Supabase. · `lib/services/supabase_service.dart`

### Supabase backend

Database schema, RLS policies, and edge workflows.

- [Database schema](https://github.com/moussax1/oaya/tree/main/supabase/migrations): SQL migrations · Tables, RLS policies, RPCs, and indexes for app data and access control. · `supabase/migrations`
- [Payment intent](https://github.com/moussax1/oaya/blob/main/supabase/functions/create-payment-intent/index.ts): Edge function · Creates Stripe payment intents for checkout. · `supabase/functions/create-payment-intent/index.ts`
- [Stripe webhook](https://github.com/moussax1/oaya/blob/main/supabase/functions/stripe-webhook/index.ts): Edge function · Receives Stripe events and updates payment/order state. · `supabase/functions/stripe-webhook/index.ts`
- [Order email](https://github.com/moussax1/oaya/blob/main/supabase/functions/send-order-email/index.ts): Edge function · Sends order confirmation email notifications. · `supabase/functions/send-order-email/index.ts`

### Native shells

Platform-specific Android and iOS launch containers.

- [Android](https://github.com/moussax1/oaya/tree/main/android/app): Platform shell · Android host app and Firebase-configured native wrapper. · `android/app`
- [iOS](https://github.com/moussax1/oaya/tree/main/ios/Runner): Platform shell · iOS host app and standard Flutter runner container. · `ios/Runner`

### Quality & delivery

Tests and CI validation around the app and backend.

- [CI](https://github.com/moussax1/oaya/blob/main/.github/workflows/ci.yml): GitHub Actions · Automated validation and build workflow. · `.github/workflows/ci.yml`
- [Tests](https://github.com/moussax1/oaya/tree/main/test): Test suite · Unit, integration, and end-to-end coverage including Supabase-backed flows. · `test`

## Connections

- Main → Router: bootstraps · App entrypoint hands off to navigation setup.
- Main → Providers: installs · Root widget wiring exposes app state.
- Router → Shopping: routes to · Navigation reaches shopping flows.
- Router → Account: routes to · Navigation reaches auth and account flows.
- Router → Checkout: routes to · Navigation reaches checkout flow.
- Router → Orders: routes to · Navigation reaches order and payment-related views.
- Router → Admin UI: routes to · Navigation reaches admin management views.
- Shopping → Widgets: uses · Feature screens compose shared UI components.
- Account → Widgets: uses · Account screens reuse common widgets.
- Checkout → Widgets: uses · Checkout screens reuse stepper and card components.
- Orders → Widgets: uses · Order views render reusable cards and progress UI.
- Shopping → Core services: reads data · Discovery and product views consume domain services.
- Checkout → Core services: writes data · Checkout persists addresses, orders, and payment state.
- Admin UI → Core services: manages · Admin screens call management-oriented services.
- Core services → Supabase client: connects via · Domain services build on the shared Supabase client.
- Core services → Stripe client: delegates payments · Checkout uses Stripe integration for card payments.
- Receipts → Core services: uses · Receipt logic formats or fetches order data.
- Supabase client → Database schema: queries · Client data access is constrained by the backend schema and policies.
- Stripe client → Payment intent: requests intent · Client obtains a payment intent before opening the payment sheet.
- Stripe webhook → Database schema: updates state · Webhook workflow persists payment and order changes.
- Order email → Database schema: reads order data · Email workflow uses persisted order details.
- Android → Main: hosts · Android launches the Flutter client.
- iOS → Main: hosts · iOS launches the Flutter client.
- CI → Tests: runs · CI validates the repository through automated tests.
- Tests → Database schema: integration target · Integration tests exercise real Supabase-backed flows.
