Syed Zubyl N | Software Developer - Flutter

What I Learned Building Flutter Applications Around Real APIs

2026-05-18T00:00:00+00:00

The Problem</h3>
Building a UI in Flutter is relatively straightforward. The real complexity begins when you connect that beautiful UI to a real-world, unpredictable REST API. Handling token expiration, offline states, local caching, and malformed JSON payloads quickly turns a simple app into a debugging nightmare.

Context</h3>
While building a mobile LMS (Learning Management System) application in Flutter, I needed to fetch course catalogs, stream videos, and issue certificates. This required robust communication with a backend API while ensuring the app remained responsive even when the user’s internet connection was spotty.

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.`

What Failed</h3> Poor UX: Users stared at loading spinners constantly.</li> Offline Experience: If a user boarded a subway, the app became completely useless. It crashed or showed generic error screens.</li> API Rate Limiting: Spamming the backend with requests every time a user switched tabs was highly inefficient.</li> </ol> What Worked & Technical Explanation</h3> I shifted to a Local-First Architecture using SQLite (via the sqflite</code> package). Instead of the UI talking directly to the API, the UI only talks to the local SQLite database. A separate background synchronization engine talks to the API. The Flow: User opens the Course List screen.</li> The UI reads immediately from SQLite and displays cached data (instant load).</li> In the background, the app fires an API request to check for updates.</li> If the API returns new data, it updates the SQLite database.</li> The UI, listening to a stream from the database, automatically rebuilds with the fresh data.</li> </ol> Handling API Failures: If an API request fails (e.g., user is offline, or the server returns a 500 error), the app simply logs the failure silently. The user is still looking at the cached data from SQLite and can continue interacting with the app. Lessons Learned</h3> Never trust the network. The network will fail, it will be slow, and it will return unexpected data.</li> Defensive Parsing: Always wrap JSON parsing in try-catch blocks or use robust code-generation tools. One unexpected null</code> field from the backend can crash the entire Flutter isolate.</li> Local State is King: For an app to feel fast and native, data must be available locally on the device the millisecond the screen renders.</li> </ol> What I Would Do Differently</h3> Instead of writing raw SQL queries for SQLite, I would adopt a higher-level reactive database like Isar or ObjectBox. They provide out-of-the-box stream capabilities that make tying local database updates directly to Flutter’s reactive UI significantly easier than building custom StreamControllers</code> over sqflite</code>.

When API Response Types Don't Match Your Flutter Model 2026-03-05T00:00:00+00:00 The Problem</h3> A Flutter application was crashing on the profile screen with a cryptic error in the console: type 'int' is not a subtype of type 'bool?'</code></pre> The app compiled perfectly, the API returned a 200 OK, but the JSON deserialization failed entirely, resulting in a red screen of death in debug mode (and a blank screen in production). Context</h3> In Dart, type safety is strict. When you parse a JSON response, you typically map a Map<String, dynamic></code> into a strongly-typed Dart object. Our model looked like this: class UserProfile { final String name; final bool? isPremium; UserProfile({required this.name, this.isPremium}); factory UserProfile.fromJson(Map<String, dynamic> json) { return UserProfile( name: json['name'], isPremium: json['isPremium'], ); } }</code></pre>What I Tried</h3> I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>). What Failed</h3> Ignoring the type cast didn’t work. The exception specifically complained about an int</code>. What Worked & Technical Explanation</h3> I intercepted the raw HTTP response body before it hit the Dart parser. { "name": "Syed", "isPremium": 1 }</code></pre> The backend developer had migrated the database, and the new database driver was serializing SQL TINYINT(1)</code> boolean columns into 1</code> and 0</code> integers in the JSON payload, rather than true</code> and false</code>. Because json['isPremium']</code> contained an integer 1</code>, Dart crashed when it implicitly tried to cast it to bool?</code>. To fix this, I implemented defensive serialization. Instead of trusting the API contract blindly, the Dart parser needs to handle potential type coercion gracefully: factory UserProfile.fromJson(Map<String, dynamic> json) { // Defensive parsing function bool? parseBool(dynamic value) { if (value == null) return null; if (value is bool) return value; if (value is int) return value == 1; if (value is String) return value.toLowerCase() == 'true'; return null; } return UserProfile( name: json['name'] ?? 'Unknown', isPremium: parseBool(json['isPremium']), ); }</code></pre>Lessons Learned</h3> API Contracts Drift: Backend implementations change, and serialization layers can inadvertently alter the types of JSON payloads (especially converting booleans to integers or numbers to strings).</li> Dart is Unforgiving: Unlike JavaScript, Dart will not automatically coerce 1</code> into true</code>. You must handle the conversion explicitly.</li> </ol> What I Would Do Differently</h3> I will use code-generation tools like json_serializable</code> or freezed</code> with custom JsonConverter</code> classes for primitive types. This abstracts away the boilerplate of defensive parsing and ensures the entire app handles API type mismatches consistently. Flutter Splash Screens vs Native Android Startup Screens 2026-01-25T00:00:00+00:00 The Problem</h3> A client wanted a highly customized, complex, animated Flutter-style splash screen to play the moment the user tapped the app icon. They wanted their branding to animate immediately, replacing the “boring” default app launch experience. Context</h3> When an Android application launches, there is an unavoidable window of time where the OS loads the app process into memory. During this time, Android displays a system-controlled launch screen. With the introduction of Android 12, Google enforced the SplashScreen</code> API, standardizing this experience to show the app icon and a background color. Flutter operates inside an Android Activity. The Flutter engine must initialize, load the Dart isolate, and render the first frame. This takes time. What I Tried</h3> The client wanted the animation to start instantly. I initially tried putting the animation directly into the first Flutter widget loaded by runApp()</code>. What Failed</h3> This resulted in a jarring experience: User taps app.</li> System shows Android 12 static splash screen (icon + background).</li> System splash disappears.</li> White flash (briefly, as Flutter attaches).</li> Flutter animated splash screen begins.</li> </ol> It looked like two separate splash screens playing back-to-back. What Worked & Technical Explanation</h3> The actual limitation is that the system-controlled Android launch splash occurs before the Flutter UI is ready, especially under Android 12+ splash-screen rules. A Flutter animation can begin after the Flutter engine/UI becomes available, but it does not replace the system launch sequence in the same way. The correct approach was a hybrid hand-off: Configure the native Android 12 SplashScreen</code> via styles.xml</code> to match the exact background color and static logo of the first frame of the Flutter animation.</li> Use the flutter_native_splash</code> package to hold the native splash screen up until Flutter is fully rendered.</li> Once Flutter renders its first frame, immediately begin the complex Flutter animation from the exact state the native splash left off.</li> </ol>  <style name="LaunchTheme" parent="Theme.SplashScreen"> <item name="windowSplashScreenBackground">@color/brand_background</item> <item name="windowSplashScreenAnimatedIcon">@drawable/launch_icon</item> <item name="postSplashScreenTheme">@style/NormalTheme</item> </style></code></pre>Lessons Learned</h3> You cannot fight the OS. The Android lifecycle dictates what happens before your application code runs. Understanding the boundaries between native Android processes and the Flutter engine is critical for smooth UX. What I Would Do Differently</h3> I will clarify the distinction between “OS Launch Screen” and “App Onboarding Animation” to clients early on. Managing expectations around what happens in the first 500ms of an app’s lifecycle prevents impossible requests later. Android App Bar Compatibility: When Client Requirements Meet Platform Defaults 2026-01-10T00:00:00+00:00 The Problem</h3> During a recent project, a client expected a highly specific app-bar appearance. The request was straightforward on paper: make the Flutter application look exactly like an Android-native/default implementation, matching a specific older Android version’s aesthetic they were used to. Context</h3> When building cross-platform applications with Flutter, the framework paints every pixel on the screen using its own rendering engine (Skia/Impeller). It does not use OEM native widgets. While Flutter’s Material widgets do an incredible job of mimicking native Android components, they default to the current Material Design guidelines (Material 3). The client, however, wanted an exact replica of an older Android native app bar behavior and shadowing. What I Tried</h3> I initially tried overriding the AppBar</code> theme properties: AppBar( elevation: 4.0, shadowColor: Colors.black.withOpacity(0.5), backgroundColor: Theme.of(context).primaryColor, title: const Text('Dashboard'), )</code></pre> This got us close, but the exact gradient of the shadow and the specific typographic alignment didn’t perfectly match the legacy Android native view the client had side-by-side on their device. What Failed</h3> Attempting to perfectly mimic a deprecated OEM native view using a modern cross-platform framework’s rendering engine became a game of diminishing returns. I tried building a completely custom PreferredSizeWidget</code> with complex box shadows, but it felt brittle. What Worked & Technical Explanation</h3> The solution was a conversation rather than a code hack. The requested result could not be reproduced exactly with the existing implementation constraints without completely changing the approach or hardcoding fragile design values. I explained to the client the difference between native Android UI conventions (which vary wildly between Android 10, 12, and 14) and Flutter’s unified rendering model. I demonstrated how adhering to Flutter’s Material 3 defaults actually provided better compatibility and visual consistency across all modern Android devices, rather than forcing an older, device-specific look. Lessons Learned</h3> Client expectations vs. platform realities: Clients often don’t know the difference between a “native default” and a “custom design.” To them, what they see on their personal phone is the “default.”</li> Push back with technical reasoning: Instead of spending hours tweaking pixel-perfect shadows to match an outdated OS, it’s better to explain the benefits of modern platform defaults.</li> </ol> What I Would Do Differently</h3> Next time, I will establish the baseline UI components using Flutter’s default Material 3 implementation during the very first design review, ensuring the client signs off on the framework’s native look before development begins.

Syed Zubyl N | Software Developer - Flutter

What I Learned Building Flutter Applications Around Real APIs

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>`

When API Response Types Don't Match Your Flutter Model

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`

Flutter Splash Screens vs Native Android Startup Screens

The Problem</h3>
A client wanted a highly customized, complex, animated Flutter-style splash screen to play the moment the user tapped the app icon. They wanted their branding to animate immediately, replacing the “boring” default app launch experience.</p>

Lessons Learned</h3>
You cannot fight the OS. The Android lifecycle dictates what happens before your application code runs. Understanding the boundaries between native Android processes and the Flutter engine is critical for smooth UX.</p>

What I Would Do Differently</h3>
I will clarify the distinction between “OS Launch Screen” and “App Onboarding Animation” to clients early on. Managing expectations around what happens in the first 500ms of an app’s lifecycle prevents impossible requests later.</p>

Android App Bar Compatibility: When Client Requirements Meet Platform Defaults

What Failed</h3>
Attempting to perfectly mimic a deprecated OEM native view using a modern cross-platform framework’s rendering engine became a game of diminishing returns. I tried building a completely custom `PreferredSizeWidget</code> with complex box shadows, but it felt brittle.</p>`

What I Would Do Differently</h3>
Next time, I will establish the baseline UI components using Flutter’s default Material 3 implementation during the very first design review, ensuring the client signs off on the framework’s native look before development begins.</p>

Syed Zubyl N | Software Developer - Flutter

What I Learned Building Flutter Applications Around Real APIs

What I Tried</h3> I initially relied solely on the network. Every time a user opened a screen, a FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>

When API Response Types Don't Match Your Flutter Model

What I Tried</h3> I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>

Flutter Splash Screens vs Native Android Startup Screens

The Problem</h3> A client wanted a highly customized, complex, animated Flutter-style splash screen to play the moment the user tapped the app icon. They wanted their branding to animate immediately, replacing the “boring” default app launch experience.</p>

Lessons Learned</h3> You cannot fight the OS. The Android lifecycle dictates what happens before your application code runs. Understanding the boundaries between native Android processes and the Flutter engine is critical for smooth UX.</p>

What I Would Do Differently</h3> I will clarify the distinction between “OS Launch Screen” and “App Onboarding Animation” to clients early on. Managing expectations around what happens in the first 500ms of an app’s lifecycle prevents impossible requests later.</p>

Android App Bar Compatibility: When Client Requirements Meet Platform Defaults

What Failed</h3> Attempting to perfectly mimic a deprecated OEM native view using a modern cross-platform framework’s rendering engine became a game of diminishing returns. I tried building a completely custom PreferredSizeWidget</code> with complex box shadows, but it felt brittle.</p>

What I Would Do Differently</h3> Next time, I will establish the baseline UI components using Flutter’s default Material 3 implementation during the very first design review, ensuring the client signs off on the framework’s native look before development begins.</p>

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>`

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`

The Problem</h3>
A client wanted a highly customized, complex, animated Flutter-style splash screen to play the moment the user tapped the app icon. They wanted their branding to animate immediately, replacing the “boring” default app launch experience.</p>

Lessons Learned</h3>
You cannot fight the OS. The Android lifecycle dictates what happens before your application code runs. Understanding the boundaries between native Android processes and the Flutter engine is critical for smooth UX.</p>

What I Would Do Differently</h3>
I will clarify the distinction between “OS Launch Screen” and “App Onboarding Animation” to clients early on. Managing expectations around what happens in the first 500ms of an app’s lifecycle prevents impossible requests later.</p>

What Failed</h3>
Attempting to perfectly mimic a deprecated OEM native view using a modern cross-platform framework’s rendering engine became a game of diminishing returns. I tried building a completely custom `PreferredSizeWidget</code> with complex box shadows, but it felt brittle.</p>`

What I Would Do Differently</h3>
Next time, I will establish the baseline UI components using Flutter’s default Material 3 implementation during the very first design review, ensuring the client signs off on the framework’s native look before development begins.</p>