Problem and ideation
Operations teams juggle stock truth, who sold what, and management visibility across phones and desks. The company’s internal reservation workflow was informal—easy to misread, hard to reconcile, and weak for auditability.
The product idea is to separate duties: people in the field should not need full database access, while leadership needs aggregation, auditability, and broadcast tools. One shared backend (inventory, orders, order_items, clients, messaging) powers two deliberate experiences—not two unrelated apps.
Product story
A single codebase encodes fast, guided flows for workers and control plus insight for admins, with a deliberately simple surface over strict data rules: one app entry, role-based routing, live inventory, and a confirm step that ties quantity changes to persisted orders.
Problem
Fragmented reservations, oversell risk, and no single place to see every rep’s activity.
Vision
One operational system: realtime catalog truth, draft-to-confirm sales, and admin oversight including analytics and messaging.
Outcome
Replaced manual coordination with a deployed internal app—streamlined ordering without constant accountant mediation.
Two roles, one product
The “final product” is not a generic inventory screen—it is a role matrix mapped to navigation and data emphasis.
| Dimension |
Worker (مندوب, user) |
Admin (admin) |
| Primary job |
Take orders against live inventory; draft cart locally; submit so stock and orders stay consistent. |
CRUD catalog; see everyone’s reservations and orders; analytics; confirm rep summaries; messaging. |
| Home hub |
Shortcuts: stock, reservation history, messages. |
Shortcuts: stock, reservations/orders, broadcast message, reps’ order board. |
| Navigation |
Bottom GNav + PageView: reservations, cart/orders, home, inventory, messages. |
Same pattern: analysis, reservations, home, inventory, messages. |
| Data emphasis |
Realtime inventory stream; SharedPreferences for pending lines until confirm. |
Streams for inventory; HTTP to Edge for enriched order lists; order summary APIs. |
Features (implementation-backed)
Authentication and onboarding — Supabase initialized from .env (URL + anon key). Splash checks session and routes to auth or the correct shell. Login uses tabs for admin vs مندوب with RTL layout.
Worker — Live inventory via inventory stream and fetches. Draft pipeline: add lines → SharedPreferences → confirm runs read qty → validate → update rows → insert orders and order_items (Arabic errors for missing SKU or oversell). Orders screen with grid-style sections, snackbars, inventory refresh on success. User reservations/history tied to user_id. Messages page reused for company-wide comms.
Admin — Inventory add/update/delete with realtime stream (DB triggers in the pipeline). Reservations and orders via Dio to an Edge Function URL from env, with defensive parsing of nested items. Analysis: orders summary per user, cards per rep, drill-down, confirm user orders with feedback. Messaging via MessageBloc and entities. Logout returns to auth.
Cross-cutting — Clean architecture per feature, repository implementations, use cases, Either + Failure from dartz. Root MultiBlocProvider for Auth, Admin (inventory, analysis, messages, reservations, orders summary), and User (inventory, orders, reservations).
UI and UX
Visual system: Centralized palette—deep bluish nav, teal/green accents, warm off-whites, red for errors—cohesive across admin and worker shells.
Typography: Google Fonts Almarai through a custom TextTheme for readable Arabic at scale.
Responsiveness: flutter_screenutil with a 390×844 design baseline, SafeArea, padding via .w / .h.
Motion: flutter_animate on splash (e.g. pulsing logo) for a polished first load.
Navigation: google_nav_bar plus a non-swipeable PageView for predictable tabs; home cards jump to the correct tab via ancestor state (WrapperNavigationState / UserWrapperNavigationState)—hub-and-spoke for non-technical users.
Density: Syncfusion Flutter DataGrid for inventory and orders where tabular accuracy matters; snackbars and BlocListener patterns keep async errors visible.
Technical architecture
Stack: Flutter (Dart 3.6+), Supabase Flutter, flutter_bloc, dio, shared_preferences, flutter_dotenv, equatable, syncfusion_flutter_datagrid, intl, google_nav_bar, flutter_screenutil, google_fonts, flutter_animate. fl_chart is in pubspec as a declared dependency for future analytics visuals—not yet referenced in lib/ at documentation time.
Role model: Session carries admin vs user. Splash resolves auth and routes into two different PageView + Google Nav Bar shells so permission boundaries stay obvious in the UI, not only in queries.
Worker path: Subscribes to inventory realtime streams; builds a local draft order; on confirm, the flow reads current quantity, validates against requested amount, rejects oversell with Arabic messaging, then updates rows and inserts orders + order_items in a coordinated sequence—integrity enforced at the application layer with room to harden further via DB transactions and constraints.
Admin path: CRUD on catalog with realtime refresh; reservations and order lists enriched via a Supabase Edge Function consumed through Dio (defensive JSON parsing for nested items, fallbacks like unknown user labels); separate BLoCs for inventory, reservations, order summaries, analysis drill-down, and messaging.
Configuration and targets: Secrets and function URLs in .env, not hardcoded. Mobile-first UI; Flutter web/ assets support a multi-platform story where relevant.
Challenges and how they were addressed
- Stock integrity on confirm — Load current quantity, compute
newQty, reject if negative, then update—documented as guarding oversell at the app layer; DB constraints and transactions are the natural next hardening step.
- Split responsibilities without duplicate backends — Same inventory stream concept for both roles; admin writes, worker consumes through confirm-only writes for stock-changing paths.
- Aggregated order views — Edge Function + Dio returns a clean list shape with validation and fallbacks (e.g. “Unknown User”, default quantities) instead of fragile client-only joins.
- Draft experience — SharedPreferences stages lines before commit—bridges spotty connectivity and UX continuity until sync.
- Role-based routing — Single entry through splash branches on role into two different
PageView apps—reduces wrong-permission UI and keeps user mental models simple.
- Arabic product UX — RTL
Directionality, Almarai, and Arabic copy in analysis empty states and errors—built for local-market operations.
What shipped (high level)
- Dual-role Flutter application (admin vs field worker) on Supabase
- Clean architecture layers, BLoC, repository pattern, and
Either-based failures
- Realtime inventory subscriptions and full admin catalog CRUD
- Order confirmation that updates inventory and creates
orders + order_items with quantity validation
- Edge Function integration via Dio for server-side order aggregation in admin grids
- Per-user order analytics and admin confirmation flows
- RTL Arabic UI, responsive layout, themed typography, and GNav + hub navigation
Engineering tradeoffs and honesty
- Charts: Describe
fl_chart only when charts are wired; today it is a declared dependency, not used in lib/—analytics remain card- and grid-driven until then.
- Draft cart MVP: Some
UserLocalDataSource paths may still carry TODOs or stubs (e.g. line edit/remove)—fair to call “planned iteration” in conversation.
- Edge vs client joins: Heavy read shapes for admin grids stay on the Edge Function so the mobile client stays thin and parsing stays resilient.
