Architecture

FLEX Mobile is a Flutter metaframework designed for building scalable, feature-rich commerce applications. This guide provides an overview of the FLEX Mobile architecture, including the core framework, starter kit app structure, and backend integrations.

Overview

FLEX follows a modular, feature-driven architecture that separates concerns into distinct layers:

• FLEX Core: Foundation framework with pluggable features
• SAP Client: Backend integration layer for SAP Commerce Cloud
• Starter Kit App: Complete commerce application built on FLEX
• FLEX UI: Design system and component library

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     FLEX Starter Kit App                        │
├─────────────────────────────────────────────────────────────────┤
│                        FLEX UI                                  │
├─────────────────────────────────────────────────────────────────┤
│                      FLEX Core                                  │
│  ┌─────────────┬─────────────┬─────────────┬─────────────────┐  │
│  │   Auth      │   i18n      │  Logging    │    Network      │  │
│  │  Feature    │  Feature    │  Feature    │   Feature       │  │
│  └─────────────┴─────────────┴─────────────┴─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                    SAP Client Package                           │
│  ┌─────────────┬─────────────┬─────────────┬─────────────────┐  │
│  │    Auth     │    Cart     │   Search    │     User        │  │
│  │   Client    │   Client    │   Client    │    Client       │  │
│  └─────────────┴─────────────┴─────────────┴─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                    Backend Services                             │
│  ┌─────────────────────────────┬─────────────────────────────┐  │
│  │     SAP Commerce Cloud      │        Contentful CMS       │  │
│  │        (OCC APIs)           │                             │  │
│  └─────────────────────────────┴─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

FLEX Core Package

The flex_core package provides the foundational framework with a plugin-based architecture.

Core Structure

flex_core/
├── src/
│   ├── core/
│   │   └── flex_core.dart          # Main framework class
│   ├── models/
│   │   └── flex_feature.dart       # Feature interface
│   ├── auth/                       # Authentication framework
│   ├── i18n/                       # Internationalization
│   ├── logging/                    # Logging system
│   ├── network/                    # Network connectivity
│   └── storage/                    # Local storage
└── flex_core.dart                  # Public exports

Feature System

FLEX uses a feature-based architecture where each feature implements the FlexFeature interface:

abstract class FlexFeature {
  void register(GetIt container);    // Register dependencies
  Future<void> initialize();        // Initialize feature
  Future<void> dispose();           // Cleanup resources
}

Initialization Pattern

Features are initialized in a specific order during app startup:

await FlexCore.initialize([
  LoggingFeature(),        // 1. Logging (foundation)
  NetworkFeature(),        // 2. Network monitoring
  StorageFeature(),        // 3. Local storage
  I18nFeature(),          // 4. Internationalization
  SapAuthFeature(),       // 5. Authentication
  CMSFeature(),           // 6. Content management
]);

SAP Client Package

The sap_client package provides SAP Commerce Cloud integration through OCC (Omnichannel Commerce) APIs.

Client Structure

sap_client/
└── src/
    ├── auth/
    │   ├── sap_auth_feature.dart   # SAP-specific auth implementation
    │   └── token_refresh_manager.dart
    ├── cart/
    │   ├── models/
    │   └── sap_cart_client.dart    # Cart operations
    ├── order/
    │   ├── models/
    │   └── sap_order_client.dart   # Order management
    ├── search/
    │   ├── models/
    │   └── sap_search_client.dart  # Product search
    ├── user/
    │   ├── models/
    │   └── sap_user_client.dart    # User management
    └── common/
        └── constants.dart          # API endpoints & constants

Client Responsibilities

• SapAuthFeature: Handles dual authentication (user + anonymous)
• SapCartClient: Shopping cart operations via OCC APIs
• SapOrderClient: Order placement and history
• SapSearchClient: Product search and filtering
• SapUserClient: User profile and account management

API Integration

All clients interact with SAP Commerce Cloud through OCC (Omnichannel Commerce) REST APIs:

SAP Commerce Cloud
├── OCC v2 APIs
│   ├── /authorizationserver/oauth/token    # Authentication
│   ├── /users/{userId}/carts               # Cart operations
│   ├── /users/{userId}/orders              # Order management
│   ├── /products/search                    # Product search
│   └── /users/{userId}                     # User profile
└── Custom Extensions (if needed)

Starter Kit Application

The FLEX Starter Kit demonstrates a complete commerce application built using FLEX architecture.

Application Structure

lib/
├── main.dart                       # App entry point & FLEX initialization
├── features/                       # Feature-based organization
│   ├── auth/                       # Authentication UI & logic
│   ├── home/                       # Homepage (CMS-driven)
│   ├── shop/                       # Product catalog & browsing
│   ├── search/                     # Search functionality
│   ├── cart/                       # Shopping cart
│   ├── checkout/                   # Checkout flow
│   ├── account/                    # User account management
│   ├── orders/                     # Order history
│   └── cms/                        # Content management system
├── repositories/                   # Data layer abstractions
│   ├── cart_repository/
│   ├── user_repository/
│   ├── search_repository/
│   └── checkout_repository/
├── shared/                         # Shared utilities & components
│   ├── flex_ui/                    # Design system components
│   ├── widgets/                    # Reusable widgets
│   └── utils/                      # Helper functions
└── routes/                         # Navigation & routing
    ├── router.dart                 # Auto-generated routes
    └── root_page.dart              # Bottom navigation shell

Feature Organization

Each feature follows a consistent structure:

features/feature_name/
├── bloc/ or cubit/                 # State management
├── models/                         # Feature-specific models
├── pages/                          # UI screens
├── widgets/                        # Feature-specific widgets
└── feature_shell_page.dart        # Feature navigation shell

Navigation Architecture

The app uses a hierarchical navigation structure:

Root Shell (Bottom Navigation)
├── Home Shell
│   ├── Homepage (CMS)
│   └── Department Pages (CMS)
├── Shop Shell
│   ├── Category Pages
│   ├── Product List
│   └── Product Details
├── Search Shell
│   ├── Search Input
│   ├── Search Results
│   └── Search Filters
├── Cart Shell
│   ├── Cart Items
│   └── Checkout Flow
└── Account Shell
    ├── Profile
    ├── Order History
    └── Settings

FLEX UI Design System

FLEX UI provides a comprehensive design system integrated with the application architecture.

Component Hierarchy

shared/flex_ui/
├── theme/
│   ├── design_tokens.dart          # Color palette & brand tokens
│   ├── brand_theme_extension.dart  # Custom theme extensions
│   └── sizes.dart                  # Consistent sizing system
├── utils/
│   ├── context_extensions.dart     # Theme & device utilities
│   └── snackbar_extensions.dart    # Branded notifications
└── widgets/                        # Reusable UI components
    ├── flex_app_bar.dart
    ├── flex_button.dart
    ├── flex_card.dart
    └── [other components]

Theme Integration

FLEX UI integrates seamlessly with Flutter’s theme system:

MaterialApp.router(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: DesignTokens.brandPrimary,
      secondary: DesignTokens.brandSecondary,
    ),
    extensions: [BrandThemeExtension.light],
  ),
)

Backend Integrations

SAP Commerce Cloud Integration

The starter kit connects to SAP Commerce Cloud (formerly hybris) through OCC APIs:

┌─────────────────┐    ┌──────────────────────────────────┐
│   FLEX App      │    │      SAP Commerce Cloud          │
│                 │    │                                  │
│  ┌──────────────┤    │  ┌─────────────────────────────┐ │
│  │ SAP Clients  ├────┼─▶│        OCC v2 APIs          │ │
│  │              │    │  │                             │ │
│  │ • Auth       │    │  │ • Authentication            │ │
│  │ • Cart       │    │  │ • Product Catalog           │ │
│  │ • Search     │    │  │ • Shopping Cart             │ │
│  │ • Order      │    │  │ • Order Management          │ │
│  │ • User       │    │  │ • User Profiles             │ │
│  └──────────────│    │  └─────────────────────────────┘ │
└─────────────────┘    └──────────────────────────────────┘

Key Integration Points:

• Authentication: OAuth2 with dual user/anonymous token support
• Product Catalog: Real-time product data, pricing, and inventory
• Shopping Cart: Persistent cart across sessions
• Order Management: Complete checkout and order tracking
• User Profiles: Account management and preferences

Contentful CMS Integration

The CMS feature integrates with Contentful for dynamic content:

┌─────────────────┐    ┌──────────────────────────────────┐
│   FLEX App      │    │          Contentful              │
│                 │    │                                  │
│  ┌──────────────┤    │  ┌─────────────────────────────┐ │
│  │ CMS Feature  ├────┼─▶│      Content Delivery       │ │
│  │              │    │  │           API               │ │
│  │ • Layouts    │    │  │                             │ │
│  │ • Content    │    │  │ • Homepage Content          │ │
│  │ • Queries    │    │  │ • Department Pages          │ │
│  │ • Utils      │    │  │ • Product Promotions        │ │
│  └──────────────│    │  │ • Marketing Banners         │ │
└─────────────────┘    │  └─────────────────────────────┘ │
                       └──────────────────────────────────┘

Content Types:

• Homepage: Hero sections, featured products, promotional content
• Department Pages: Category-specific layouts and content
• Product Promotions: Dynamic pricing and promotional banners
• Marketing Content: Seasonal campaigns and announcements

Data Flow Architecture

State Management Pattern

The application uses BLoC pattern with repository abstraction:

┌─────────────┐    ┌─────────────────┐    ┌──────────────────┐    ┌─────────────┐
│     UI      │    │      BLoC       │    │   Repository     │    │  API Client │
│   Widgets   ├───▶│   (Business     ├───▶│  (Data Layer     ├───▶│             │
│             │    │     Logic)      │    │   Abstraction)   │    │ (SAP/CMS)   │
└─────────────┘    └─────────────────┘    └──────────────────┘    └─────────────┘
       ▲                      │                       │                       │
       │                      ▼                       │                       │
       └──────────────── State Updates ◀──────────────┘                       │
                                                                               │
       ┌─────────────────────────────────────────────────────────────────────┘
       ▼
┌──────────────────┐
│   Local Storage  │
│   (Caching &     │
│   Offline Data)  │
└──────────────────┘

Authentication Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                        Authentication Flow                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  1. App Start                                                           │
│     ├─ Check for stored user token                                      │
│     ├─ If valid: Set user authentication                                │
│     └─ If invalid/missing: Get anonymous token                          │
│                                                                         │
│  2. User Login                                                          │
│     ├─ Username/Password → SAP OAuth2 endpoint                          │
│     ├─ Store user token securely                                        │
│     ├─ Switch from anonymous to user authentication                     │
│     └─ Update all HTTP clients with user token                          │
│                                                                         │
│  3. Token Refresh                                                       │
│     ├─ Automatic refresh on 401 responses                               │
│     ├─ Use refresh token to get new access token                        │
│     └─ Fallback to anonymous if user refresh fails                      │
│                                                                         │
│  4. Logout                                                              │
│     ├─ Clear user token from secure storage                             │
│     ├─ Switch back to anonymous authentication                          │
│     └─ Clear user-specific data                                         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Deployment Architecture

Build Configuration

The starter kit supports multiple deployment targets:

┌─────────────────────────────────────────────────────────────────┐
│                      Build Targets                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Development                                                    │
│  ├─ Local SAP Commerce instance                                 │
│  ├─ Contentful development space                                │
│  ├─ Debug logging enabled                                       │
│  └─ Hot reload & development tools                              │
│                                                                 │
│  Staging                                                        │
│  ├─ Staging SAP Commerce environment                            │
│  ├─ Contentful staging space                                    │
│  ├─ Limited logging                                             │
│  └─ Performance profiling                                       │
│                                                                 │
│  Production                                                     │
│  ├─ Production SAP Commerce Cloud                               │
│  ├─ Contentful production space                                 │
│  ├─ Error logging only                                          │
│  ├─ Crash reporting integration                                 │
│  └─ Analytics integration                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Environment Configuration

Different environments are configured through .env files:

# Development
SAP_BASE_URL=https://dev.sap-commerce.company.com
CONTENTFUL_ENVIRONMENT=development

# Staging
SAP_BASE_URL=https://staging.sap-commerce.company.com
CONTENTFUL_ENVIRONMENT=staging

# Production
SAP_BASE_URL=https://api.sap-commerce.company.com
CONTENTFUL_ENVIRONMENT=master

Extensibility & Customization

Adding New Features

The FLEX architecture supports easy extension:

1. Create Feature Package: Follow the FlexFeature interface
2. Register Dependencies: Use the DI container
3. Initialize Feature: Add to the initialization sequence
4. Integrate UI: Add to the navigation structure

Custom Backend Integration

Replace SAP integration with other commerce platforms:

// Example: Shopify integration
class ShopifyClientPackage {
  // Implement same interface as SAP clients
  ShopifyAuthClient authClient;
  ShopifyCartClient cartClient;
  ShopifyOrderClient orderClient;
  // ... other clients
}

UI Customization

Override design tokens and components:

class CustomDesignTokens {
  static const Color brandPrimary = Color(0xFF1976D2);
  static const Color brandSecondary = Color(0xFFF57C00);
  // ... other customizations
}

Performance Considerations

Lazy Loading

Features and dependencies are loaded on-demand:

// Lazy registration prevents unnecessary initialization
container.registerLazySingleton<CartRepository>(
  () => CartRepository(/* dependencies */),
);

Caching Strategy

Multi-level caching improves performance:

• Memory Cache: Frequently accessed data
• Local Storage: Persistent offline data
• HTTP Cache: Network response caching
• Image Cache: Optimized image loading

Resource Management

Proper cleanup prevents memory leaks:

@override
Future<void> dispose() async {
  await _streamSubscription.cancel();
  await _animationController.dispose();
  // ... other cleanup
}

Security Architecture

Token Security

• Secure Storage: User tokens encrypted at rest
• Token Rotation: Automatic refresh with fallback
• Scope Limitation: Minimal required permissions

API Security

• Certificate Pinning: Production API security
• Request Signing: Optional additional security layer
• Rate Limiting: Client-side request throttling

Data Protection

• PII Handling: Secure user data management
• Cache Security: Sensitive data excluded from cache
• Audit Logging: Security event tracking

Monitoring & Observability

Logging Strategy

• Structured Logging: Consistent log format
• Log Levels: Appropriate verbosity per environment
• Remote Logging: Production error tracking

Analytics Integration

• User Journey: Navigation and conversion tracking
• Performance: App performance monitoring
• Business Metrics: Commerce-specific KPIs

Error Handling

• Crash Reporting: Automatic error reporting
• Graceful Degradation: Fallback functionality
• User Feedback: Error communication

Getting Started

Prerequisites

1. Flutter SDK: Latest stable version
2. SAP Commerce Cloud: Access to OCC APIs
3. Contentful Account: CMS integration
4. Development Environment: IDE with Flutter support

Installation

# Install FLEX CLI
npm install -g @flex/cli

# Create new project
flexcli new my_commerce_app --template sap

# Configure environment
cp example.env .env
# Edit .env with your credentials

# Run the app
flutter run

First Steps

1. Configure Backend: Update .env with SAP and Contentful credentials
2. Customize Branding: Modify design tokens in DesignTokens
3. Configure Locales: Set supported languages in I18nFeature
4. Test Integration: Verify API connectivity
5. Build Features: Start with homepage customization

This architecture provides a solid foundation for building scalable, maintainable commerce applications while maintaining flexibility for customization and extension.