How moussax1/oaya works
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: router.dart Router · services Core services · main.dart Main · widgets Widgets
Components 22
Flutter app
Client UI, routing, state, and feature screens.
- Main · App entrypoint that initializes the client shell.
lib/main.dart - Router · Route map for auth, shopping, checkout, profile, and admin flows.
lib/router.dart - Providers · Shared app state and async state wiring for the client.
lib/providers/providers.dart - Theme · Centralized colors and visual constants used across screens.
lib/constants/theme.dart - Widgets · Reusable UI building blocks for product, cart, order, and loading states.
lib/widgets - Shopping · Discovery and product journey screens for home, search, details, and wishlist.
lib/screens - Account · Authentication, profile, settings, support, and notification screens.
lib/screens - Checkout · Address, payment, and success flow for completing purchases.
lib/screens/checkout - Orders · Order confirmation, history, reviews, and payment methods views.
lib/screens - Admin UI · Management screens for products, orders, and users.
lib/screens/admin - Core services · Supabase access plus domain services for products, cart, orders, wishlist, reviews, addresses, and payments.
lib/services - Stripe client · Client-side payment-sheet integration and client secret handling.
lib/services/stripe_service.dart - Receipts · Receipt generation and cross-platform download adapters.
lib/services/receipt_service.dart - Supabase client · Initializes and wraps app access to Supabase.
lib/services/supabase_service.dart
Supabase backend
Database schema, RLS policies, and edge workflows.
- Database schema · Tables, RLS policies, RPCs, and indexes for app data and access control.
supabase/migrations - Payment intent · Creates Stripe payment intents for checkout.
supabase/functions/create-payment-intent/index.ts - Stripe webhook · Receives Stripe events and updates payment/order state.
supabase/functions/stripe-webhook/index.ts - Order email · Sends order confirmation email notifications.
supabase/functions/send-order-email/index.ts
Native shells
Platform-specific Android and iOS launch containers.
Connections 25
- 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.