Flutter widget architecture

class UserProfileHeader extends StatelessWidget {
  const UserProfileHeader({
    super.key,
    required this.avatarUrl,
    required this.displayName,
  });

  final String avatarUrl;
  final String displayName;

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        CircleAvatar(backgroundImage: NetworkImage(avatarUrl)),
        Text(displayName, style: Theme.of(context).textTheme.headlineSmall),
      ],
    );
  }
}

class CartSummary extends StatelessWidget {
  const CartSummary({super.key});

  @override
  Widget build(BuildContext context) {
    // Only rebuilds when totalPrice changes
    final totalPrice = context.select((CartProvider p) => p.totalPrice);
    
    return Text(
      'Total: \$${totalPrice.toStringAsFixed(2)}',
      style: Theme.of(context).textTheme.titleLarge,
    );
  }
}

RepaintBoundary(
  child: AnimatedBuilder(
    animation: _controller,
    builder: (_, child) => Transform.rotate(
      angle: _controller.value,
      child: child,
    ),
    child: const Icon(Icons.refresh, size: 48),
  ),
)

tomPaint, or MultiChildRenderObjectWidgetcan’t express your layout, implement a customRenderBox`.

class RadialLayout extends MultiChildRenderObjectWidget {
  const RadialLayout({super.key, required super.children});

  @override
  RenderRadialLayout createRenderObject(BuildContext context) => RenderRadialLayout();
}

class RenderRadialLayout extends RenderBox with ContainerRenderObjectMixin<RenderBox, RadialLayoutParentData> {
  @override
  void performLayout() {
    // Calculate positions, set layout constraints
    // Avoid calling layout() on children unless size changes
  }

  @override
  void paint(PaintingContext context, Offset offset) {
    // Paint children at computed positions
  }
}

This bypasses the Element tree entirely for layout calculations, reducing rebuild overhead to zero.

Architecture Decisions & Rationale

• Composition over inheritance: Widgets are functions of state. Compose small, pure widgets instead of extending base classes.
• Unidirectional data flow: State flows down, events flow up. Prevents circular rebuild dependencies.
• Separation of concerns: UI configuration (Widget) → Lifecycle/State (Element) → Layout/Paint (RenderObject). Never mix them.
• Profile before optimizing: Use Flutter DevTools → Performance → Widget rebuilds to identify hotspots. Optimize only where data indicates bottleneck.

---

Pitfall Guide

1. Treating StatefulWidget as a Data Store

StatefulWidget is a lifecycle manager, not a data container. Storing business data in State forces full subtree rebuilds on every mutation. Fix: Lift state to a provider, Riverpod, or BLoC. Keep State only for animation controllers, focus nodes, or form keys.

2. Omitting const on Stateless Widgets

Every non-const widget triggers Element diffing. In a 500-widget tree, this adds 8–15ms per frame. Fix: Add const to all widgets with static properties. Use @immutable annotation to enforce it at compile time.

3. Misusing Key in Lists

UniqueKey in ListView.builder forces the framework to treat every item as new on every rebuild. This destroys recycling. Fix: Use ValueKey(item.id) or ObjectKey(item). Only use GlobalKey when you must access widget state from outside the tree (rare).

4. Calling setState Inside build() or initState()

This creates infinite rebuild loops or violates lifecycle contracts. The framework warns but doesn’t always crash. Fix: Guard state updates with WidgetsBinding.instance.addPostFrameCallback or move logic to didChangeDependencies/initState with mounted checks.

5. Ignoring didUpdateWidget

When parent passes new configuration, didUpdateWidget lets you diff old vs new values and skip expensive work. Fix: Implement didUpdateWidget(covariant MyWidget oldWidget) and compare properties before triggering animations or network calls.

6. Mixing Business Logic with UI Reconstruction

Calling APIs, parsing JSON, or running calculations inside build() blocks the UI thread and causes jank. Fix: Move side effects to controllers, providers, or initState. build() must be pure and synchronous.

7. Not Using RepaintBoundary for Animated/Scrolling Content

Frequent repaints without boundaries force the entire screen to rasterize. Fix: Wrap independent visual layers in RepaintBoundary. Verify with DevTools → Performance → Paint profiler.

Production Best Practices:

• Run flutter build apk --profile and test on mid-tier devices, not flagship simulators.
• Use --track-widget-creation in debug to catch missing const.
• Benchmark with flutter run --profile and DevTools timeline. Target <16ms frame budget.
• Treat widget trees as directed acyclic graphs. Cycles cause memory leaks and rebuild storms.

---

Production Bundle

Action Checklist

• Audit all StatelessWidget and StatefulWidget constructors for missing const modifiers
• Replace Provider.of<T>(context) with context.select() to isolate rebuild boundaries
• Verify all ListView.builder/GridView.builder items use ValueKey or ObjectKey, never UniqueKey
• Wrap independent animated or scrolling components in RepaintBoundary
• Move all network calls, JSON parsing, and heavy computations out of build() methods
• Implement didUpdateWidget for widgets receiving frequent configuration changes
• Profile with Flutter DevTools → Performance → Widget rebuilds and validate frame budget <16ms

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple static UI (headers, footers)	const StatelessWidget	Zero diffing, framework caches element	Negligible
Frequent state updates (counters, toggles)	StatelessWidget + ValueNotifier/Selector	Isolates rebuilds to dependent widgets only	Low
Complex lists with dynamic items	ListView.builder + ValueKey + RepaintBoundary	Enables recycling, prevents full subtree rebuilds	Medium
Custom layout (radial, overlapping, grid)	MultiChildRenderObjectWidget	Bypasses Element tree, direct layout control	High (dev time)
Animation-heavy UI (transitions, parallax)	AnimatedBuilder + RepaintBoundary	Caches raster, limits repaint scope	Low-Medium
Global state shared across screens	Riverpod/Provider with granular scopes	Prevents cross-screen rebuild pollution	Medium

Configuration Template

// lib/core/architecture/widget_skeleton.dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

// 1. Pure configuration widget (no state, const-friendly)
class FeatureCard extends StatelessWidget {
  const FeatureCard({
    super.key,
    required this.title,
    required this.icon,
    required this.onTap,
  });

  final String title;
  final IconData icon;
  final VoidCallback onTap;

  @override
  Widget build(BuildContext context) {
    return Card(
      child: InkWell(
        onTap: onTap,
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          child: Row(
            children: [
              Icon(icon, size: 32),
              const SizedBox(width: 12),
              Text(title, style: Theme.of(context).textTheme.titleMedium),
            ],
          ),
        ),
      ),
    );
  }
}

// 2. Granular rebuild boundary using Riverpod selector
class FeatureList extends ConsumerWidget {
  const FeatureList({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Only rebuilds when list data changes, not when UI theme or other state changes
    final features = ref.watch(featureProvider);
    
    return ListView.builder(
      itemCount: features.length,
      itemBuilder: (context, index) {
        final item = features[index];
        return RepaintBoundary(
          child: FeatureCard(
            key: ValueKey(item.id),
            title: item.name,
            icon: item.icon,
            onTap: () => ref.read(featureControllerProvider.notifier).selectFeature(item.id),
          ),
        );
      },
    );
  }
}

// 3. State provider (separated from UI)
@riverpod
class FeatureProvider extends _$FeatureProvider {
  @override
  List<Feature> build() => [];
}

class Feature {
  final String id;
  final String name;
  final IconData icon;
  Feature({required this.id, required this.name, required this.icon});
}

Quick Start Guide

1. Enable profiling: Run flutter run --profile --track-widget-creation to capture rebuild data without debug overhead.
2. Identify hotspots: Open Flutter DevTools → Performance → Widget rebuilds. Sort by "Rebuild Count" and note widgets exceeding 50 rebuilds/frame.
3. Apply boundaries: Add const to constructors, wrap hot widgets in RepaintBoundary, and replace broad state listeners with context.select() or Selector.
4. Validate: Run the same profile session. Confirm frame budget stays under 16ms, rebuild count drops >60%, and memory allocation stabilizes.
5. Lock architecture: Add flutter analyze lint rules (prefer_const_constructors, avoid_redundant_argument_values) to CI pipeline to prevent regression.

Flutter’s widget architecture isn’t a UI layer. It’s a rendering pipeline. Treat widgets as configuration, elements as lifecycle managers, and render objects as layout engines, and you’ll eliminate rebuild storms before they impact production.