Flutter Export Strategy - Platform-Agnostic Universe Building

How the Modular Universe Builder maintains platform-agnostic layouts for Flutter/mobile export

Flutter Export Strategy - Platform-Agnostic Universe Building

🎯 Core Philosophy

The Modular Universe Builder is designed to be platform-agnostic from the ground up, allowing universes built in the web interface to be exported to Flutter, React Native, and other platforms without losing structure or functionality.

🏗️ Architecture Decisions

Layout System: Flexbox First

Why Flexbox is the Default:

✅ Cross-platform: Flutter, React Native, and CSS all support Flexbox
✅ Responsive: Adapts naturally to different screen sizes
✅ Mobile-friendly: Works seamlessly on iOS, Android, web
✅ Future-proof: Platform-agnostic approach

CSS Grid as Optional Enhancement:

⚠️ Web-only: Advanced web layouts
⚠️ Limited mobile support: Not all platforms
✅ Use case: Complex desktop dashboards

How to Choose

// DEFAULT: Always use Flexbox for cross-platform projects
layoutConfig = {
  type: 'flexbox',  // ✅ Works everywhere
  flexbox: {
    direction: 'column',
    justifyContent: 'flex-start',
    alignItems: 'stretch',
    gap: '16px'
  }
};

// ADVANCED: Use CSS Grid only for web-specific layouts
layoutConfig = {
  type: 'grid',  // ⚠️ Web-only
  grid: {
    rows: ['auto', '1fr', 'auto'],
    columns: ['250px', '1fr', '300px'],
    gap: '16px'
  }
};

📱 Mobile/Flutter Considerations

1. Responsive Section Behavior

Web (Desktop):

┌─────────────────────────────────────┐
│  Sidebar  │   Main   │   Config    │  ← 3 columns
└─────────────────────────────────────┘

Mobile (Flutter):

┌───────────┐
│  Sidebar  │  ← Stack vertically
├───────────┤
│   Main    │
├───────────┤
│  Config   │
└───────────┘

Implementation:

// Sections have responsive visibility settings
section: SectionConfig = {
  visibility: {
    mobile: true,    // Show on mobile
    tablet: true,    // Show on tablet
    desktop: true    // Show on desktop
  }
};

2. Flexbox Direction Switching

Desktop Layout (Flexbox Row):

layoutConfig = {
  type: 'flexbox',
  flexbox: {
    direction: 'row',  // Horizontal on desktop
    gap: '16px'
  }
};

Mobile Layout (Auto-switch to Column):

// Flutter export automatically converts:
// row → column (for mobile)
// justifyContent: space-between → flex-start (mobile)
// Large gaps → smaller gaps (mobile)

3. Platform-Agnostic Storage

Storage Format (Platform-independent JSON):

{
  "type": "flexbox",
  "flexbox": {
    "direction": "column",
    "justifyContent": "flex-start",
    "alignItems": "stretch",
    "gap": "16px"
  },
  "sections": [
    {
      "id": "section_1",
      "contentType": "module",
      "moduleId": "top-nav",
      "positioning": { "position": "relative" },
      "behavior": {
        "scrollable": true,
        "collapsible": false,
        "resizable": true,
        "draggable": true
      },
      "visibility": {
        "mobile": true,
        "tablet": true,
        "desktop": true
      }
    }
  ]
}

Flutter Conversion:

// GgStorage → JSON → Flutter Widget Tree
Column(  // Flexbox direction: column
  crossAxisAlignment: CrossAxisAlignment.stretch,  // alignItems: stretch
  mainAxisAlignment: MainAxisAlignment.start,  // justifyContent: flex-start
  children: [
    // Each section becomes a Flutter widget
    ModuleWidget(moduleId: 'top-nav'),
    SizedBox(height: 16),  // gap
    ModuleWidget(moduleId: 'content'),
  ],
)

🔄 Export Pipeline

Step 1: Platform-Agnostic Data

// Built in web UI (Modular Universe Builder)
const universeLayout: LayoutConfiguration = {
  type: 'flexbox',  // Platform-agnostic
  sections: [/* ... */]
};

// Stored in GgStorage
await storage.set(`universe_${id}_layout`, universeLayout);

Step 2: Flutter Export Service

// PlatformExportService generates Flutter code
const flutterCode = await exportService.exportToFlutter(universeLayout);

Step 3: Flutter Widget Generation

// Generated Flutter code
class UniverseView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(  // From flexbox.direction: 'column'
      children: [
        // Sections rendered as Flutter widgets
        TopNavigationModule(),
        Expanded(child: MainContentModule()),
        FooterModule(),
      ],
    );
  }
}

🎨 Styling Strategy

Platform-Agnostic Properties

Supported Everywhere:

✅ padding, margin → Converted to EdgeInsets in Flutter
✅ backgroundColor → Converted to Color in Flutter
✅ borderRadius → Converted to BorderRadius in Flutter
✅ Flexbox properties → Converted to Column/Row/Flex in Flutter

Web-Specific (Not exported):

⚠️ box-shadow → Flutter uses elevation/shadows differently
⚠️ CSS Grid properties → Fallback to Column/Row
⚠️ Advanced CSS selectors → Not applicable

Example Conversion

Web CSS (From section config):

.section {
  padding: 16px;
  margin: 8px;
  background-color: #1a1a1a;
  border-radius: 8px;
}

Flutter Dart (Generated):

Container(
  padding: EdgeInsets.all(16),
  margin: EdgeInsets.all(8),
  decoration: BoxDecoration(
    color: Color(0xFF1A1A1A),
    borderRadius: BorderRadius.circular(8),
  ),
)

📐 Responsive Breakpoints

Automatic Adaptation

Desktop (width > 1024px):

Use full layout as designed
All sections visible (if visibility.desktop = true)
Horizontal layouts (rows) work well

Tablet (width 768-1024px):

May switch some rows to columns
Adjust gaps/spacing
Some sidebars may collapse

Mobile (width < 768px):

Force vertical stacking (all rows → columns)
Hide/collapse optional sections
Reduce gaps and padding
Touch-friendly sizing

Implementation

// Section-level responsive control
section: SectionConfig = {
  visibility: {
    mobile: true,     // Force show/hide on mobile
    tablet: true,     // Force show/hide on tablet
    desktop: true     // Force show/hide on desktop
  },
  
  // Mobile-specific overrides (future)
  mobileOverrides: {
    flexGrow: 0,
    order: 1,
    padding: '8px'  // Smaller padding on mobile
  }
};

🔮 Future Enhancements

1. Platform-Specific Overrides

section: SectionConfig = {
  // Base configuration (used everywhere)
  padding: '16px',
  
  // Platform overrides
  platformOverrides: {
    flutter: {
      padding: '12.0',  // Flutter uses different units
      elevation: 2.0    // Flutter-specific property
    },
    web: {
      boxShadow: '0 2px 8px rgba(0,0,0,0.1)'  // Web-specific
    }
  }
};

2. Responsive Layout Preview

Preview mobile/tablet/desktop views in builder
Visual breakpoint indicators
Test responsive behavior before export

3. Platform-Specific Widgets

Define alternate widgets for different platforms
E.g., Material Design for Android, Cupertino for iOS
Web-specific optimizations

✅ Best Practices

DO ✅

Always use Flexbox for cross-platform projects
```
layoutConfig = { type: 'flexbox', ... };
```

Set responsive visibility explicitly

visibility: { mobile: true, tablet: true, desktop: true }

Use relative units (avoid fixed pixel widths for cross-platform)

flexBasis: '30%'  // ✅ Scales to screen
width: '300px'    // ⚠️ Fixed, may not scale

Test on multiple screen sizes
- Desktop (1920x1080)
- Tablet (768x1024)
- Mobile (375x667)

DON'T ❌

Don't use CSS Grid for mobile/Flutter projects

layoutConfig = { type: 'grid', ... };  // ❌ Won't export to Flutter

Don't rely on web-only CSS

.section {
  backdrop-filter: blur(10px);  // ❌ Web-only
}

Don't assume fixed screen sizes

width: '1920px'  // ❌ Breaks on mobile

📊 Platform Compatibility Matrix

Feature	Web	Flutter	React Native	Notes
Flexbox	✅	✅	✅	Fully supported everywhere
CSS Grid	✅	❌	❌	Web-only
Section visibility	✅	✅	✅	Responsive control
Padding/Margin	✅	✅	✅	Units may differ
Background color	✅	✅	✅	Color format conversion
Border radius	✅	✅	✅	Supported
Box shadow	✅	⚠️	⚠️	Different implementation
Drag-and-drop	✅	❌	❌	Builder-only feature

🎉 Summary

The Modular Universe Builder is built with Flutter export as a first-class citizen:

✅ Flexbox-first architecture ensures cross-platform compatibility ✅ Platform-agnostic storage enables easy export ✅ Responsive visibility controls adapt to screen sizes ✅ Clean separation between builder features and runtime layout

Result: Universes built in the web interface can be exported to Flutter/mobile without losing structure or requiring redesign! 🚀

Related Documentation:

layout-types.ts - Type definitions for layouts
platform-export.service.ts - Export implementation
TESTING_GUIDE.md - Testing cross-platform layouts