Feat: Add complete introduction to Flutter

.cspell.yaml

@@ -31,6 +31,7 @@ words:
   - evenodd
   - ffigen
   - jank
+  - janky
   - libapp
   - libflutter
   - libupdater
@@ -40,6 +41,7 @@ words:
   - microsoftonline
   - mipmap
   - mozallowfullscreen
+  - nubank
   - podfile
   - prefs
   - previewable
@@ -51,6 +53,7 @@ words:
   - subosito
   - temurin
   - webkitallowfullscreen
+  - widgetbook
   - xcarchive
   - xcframework
   - xcframeworks

src/content/docs/flutter-concepts/complete-introduction-flutter.mdx

@@ -0,0 +1,307 @@
+---
+title: What is Flutter?
+description: An Introduction to Flutter for Developers
+sidebar:
+  order: 1
+---
+
+In the early stages of mobile development, you had two options: build your app
+twice (once for iOS in Swift, once for Android in Kotlin) or compromise on
+quality by wrapping a web view. The first option doubled your engineering costs
+and created divergent user experiences. The second option left users with janky
+interfaces that felt wrong on both platforms.
+
+Flutter changed this equation. It's Google's open source UI toolkit for building
+natively compiled applications for mobile, web, and desktop from a single
+codebase. Unlike earlier cross-platform frameworks that wrapped native
+components, Flutter draws its own pixels, giving you complete control over every
+frame that renders on screen.
+
+Flutter isn't experimental anymore. Companies like
+[eBay Motors](https://flutter.dev/showcase/ebay) use it for their vehicle
+marketplace app. [BMW](https://flutter.dev/showcase/bmw) uses it for its
+connected car experiences. [Nubank](https://flutter.dev/showcase/nubank), one of
+the world's largest digital banks, built its entire mobile platform with Flutter
+and serves over 100 million customers.
+
+This article explains how Flutter works under the hood, why businesses and
+developers choose it, and the ecosystem of tools and agencies that make it
+production-ready for enterprise teams.
+
+## How Flutter Works: The Architecture
+
+Most cross-platform frameworks act as translators. They take your code and
+convert it into native iOS and Android UI components at runtime. This
+translation layer creates performance bottlenecks and inconsistencies because
+iOS buttons don't behave exactly like Android buttons.
+
+Flutter takes a different approach. It doesn't use native platform widgets at
+all. Instead, it draws every pixel itself using a high-performance graphics
+engine. Think of it like a video game engine, but for building apps. On iOS,
+Android, desktop, and web, Flutter controls the entire rendering pipeline from
+your code down to the pixels on screen.
+
+This approach starts with [Skia](https://skia.org/), the same 2D graphics
+library that powers Chrome and Android. In 2022-24, Flutter introduced and set
+as default [Impeller](https://docs.flutter.dev/perf/impeller), a next-generation
+rendering engine that compiles shaders ahead of time for even better
+performance. When your Flutter app renders a button, it's not asking the OS for
+a button component. It's drawing the exact pixels that make up that button, down
+to the shadow and animation curves.
+
+Google chose [Dart](https://dart.dev/) as the programming language for Flutter
+for specific technical reasons. Dart compiles to native ARM machine code on
+mobile, which means your production app runs at full speed without a JavaScript
+bridge or interpreter. During development, Dart's Just-in-Time (JIT) compiler
+powers Hot Reload, one of Flutter's most praised features. You can change your
+code and see the result in under a second, without losing your app's state or
+restarting.
+
+Flutter's architecture centers on widgets. Everything in Flutter is a widget,
+from structural elements like rows and columns to styling properties like
+padding and margins. You compose these widgets together to build your interface.
+A button isn't a single object. It's a composition of widgets for gesture
+detection, padding, material effects, and text styling. This composability makes
+Flutter interfaces predictable and testable.
+
+The framework uses Ahead-of-Time (AOT) compilation for production builds. Your
+Dart code compiles directly to native ARM code, eliminating the runtime overhead
+of interpretation or just-in-time compilation. This is why Flutter apps can
+maintain 60fps (or 120fps on high-refresh displays) consistently. The
+framework's
+[rendering pipeline is designed to complete all work for a frame in under 16 milliseconds](https://docs.flutter.dev/tools/devtools/performance#:~:text=This%20means%20that%2C%20approximately%20every%2016ms%2C%20the%20UI%20updates%20to%20reflect%20animations%20or%20other%20changes%20to%20the%20UI.),
+the budget for 60fps rendering.
+
+Flutter's architecture has one more advantage: consistency across platforms.
+Because Flutter controls its own rendering, a button looks identical on iOS 15,
+Android 13, and a three-year-old device. You're not at the mercy of platform
+differences or OS version fragmentation.
+
+## Why Developers and Businesses Choose Flutter
+
+Hot Reload changed how mobile developers work. Before Flutter, changing a UI
+element meant recompiling your app, reinstalling it, and navigating back to the
+screen you were working on. This cycle took 30-60 seconds. With Hot Reload, you
+save your file and see the change in a few seconds, with your app's current
+state preserved. You can iterate on animations, test edge cases, and experiment
+with designs at a pace that wasn't possible before.
+
+For businesses, the math is simple. You write one codebase instead of two. That
+means one team instead of two separate iOS and Android teams. You don't need to
+synchronize features between platforms or maintain parity between codebases.
+When you fix a bug, it's fixed everywhere. When you ship a feature, it ships to
+all your users at once.
+
+Flutter gives you pixel-perfect control over your interface on every screen
+size. You're not limited by platform conventions or native component libraries.
+Companies building design systems appreciate this control. You can match your
+brand guidelines exactly, animate transitions the way your designers envisioned,
+and create custom UI components that work identically across mobile, desktop,
+and web.
+
+Dart's null safety system, introduced in Dart 2.12, prevents null reference
+errors at compile time. These errors are responsible for billions of dollars in
+software failures across the industry. Dart's type system catches null errors
+before you ship code to users. The language also supports modern features like
+async/await for handling asynchronous operations, strong type inference, and
+extension methods for adding functionality to existing classes.
+
+The business case extends beyond engineering efficiency. Teams shipping Flutter
+apps report faster time-to-market because they're not coordinating two
+platform-specific releases. They can experiment more freely because changes are
+cheaper to make. Most importantly, they can maintain quality standards across
+all platforms without fragmenting their engineering resources.
+
+## The Flutter Ecosystem: Tools and Agencies
+
+A framework is only useful if you can actually ship production apps with it.
+Flutter has matured into a commercial ecosystem with specialized tools and
+agencies that handle the full application lifecycle.
+
+### The Tooling Stack
+
+**Shorebird** solves one of mobile development's biggest frustrations: app store
+review times. When you find a critical bug, you can't just push a fix. You have
+to submit an update, wait 24-48 hours for Apple's review (longer on weekends),
+then wait for users to actually install the update.
+[Shorebird](https://shorebird.dev) enables
+[over-the-air updates](https://docs.shorebird.dev/code-push/) for Flutter apps.
+You can [patch bugs](https://docs.shorebird.dev/code-push/patch/) and ship
+changes directly to your users' devices without going through the store review
+process. It works by updating your Dart code while keeping your native shell
+unchanged, which keeps you compliant with
+[App Store](https://docs.shorebird.dev/code-push/guides/stores/app-store/) and
+[Play Store](https://docs.shorebird.dev/code-push/guides/stores/play-store/)
+guidelines.
+
+**Codemagic** is a CI/CD platform built specifically for mobile apps. Generic CI
+systems like GitHub Actions work, but they weren't designed for the specific
+needs of mobile builds: managing certificates, provisioning profiles,
+platform-specific signing, and coordinating releases across multiple stores.
+[Codemagic](https://codemagic.io/) handles these mobile-specific workflows out
+of the box. It
+[integrates with Shorebird](https://docs.shorebird.dev/code-push/ci/codemagic/)
+and provides specialized workflows for releasing to the App Store, Play Store,
+and Firebase App Distribution.
+
+**ServerPod** lets you build your backend in Dart. Most Flutter apps talk to a
+backend written in Node.js, Python, or Go. [ServerPod](https://serverpod.dev/)
+lets you write full-stack applications in a single language. It includes an ORM,
+API generation, authentication, and real-time communication. If you're building
+a Flutter app and need a backend, ServerPod means your entire team can work in
+Dart with shared types and business logic between client and server.
+
+**Widgetbook** is Storybook for Flutter. It creates a catalog of your UI
+components where you can develop widgets in isolation, test them with different
+data, and document their usage. When you're building a design system or working
+on a team where designers need to review components,
+[Widgetbook](https://www.widgetbook.io/) provides a development environment
+focused purely on UI components, separate from your app's business logic and
+navigation.
+
+### The Experts: Agencies
+
+Not every company has the internal expertise or bandwidth to build a Flutter app
+from scratch. For businesses looking to scale quickly without an internal team,
+hiring a specialized Flutter app development company is a common path.
+
+**Very Good Ventures (VGV)** is known for defining architecture patterns and
+best practices in the Flutter community. They've worked with companies like
+Betterment and Hamilton, building production Flutter apps that handle millions
+of users. VGV open sources many of their tools, including
+[Very Good CLI](https://cli.vgv.dev/) for scaffolding projects and Very Good
+Coverage for enforcing code coverage standards. When companies need to establish
+patterns for large Flutter codebases,
+[VGV's architectural guidance](https://verygood.ventures/) shapes how teams
+structure their apps.
+
+**LeanCode** specializes in enterprise Flutter applications. They've built apps
+for European banks, healthcare providers, and logistics companies where
+security, compliance, and scale matter. Their expertise includes integrating
+Flutter with existing enterprise systems, implementing complex authentication
+flows, and optimizing performance for apps with heavy data requirements.
+
+A dedicated Flutter mobile app development company can accelerate time-to-market
+by using pre-built modules, established patterns, and deep knowledge of the
+platform's edge cases. These agencies have encountered and solved the problems
+you'll face, from handling offline sync to optimizing app size to debugging
+platform-specific issues.
+
+## Flutter vs. The Competition
+
+It is also important to look at Flutter’s competitors to understand the benefits
+that you get over them
+
+### Flutter vs. React Native
+
+React Native uses a JavaScript bridge to communicate with native platform
+components. When you render a button in React Native, your JavaScript code sends
+a message across this bridge to create a native iOS or Android button. This
+bridge adds latency and complexity. Flutter eliminates the bridge entirely by
+rendering its own components. This architectural difference means Flutter
+delivers more consistent performance, especially in complex UIs with heavy
+animation or frequent state changes.
+
+React Native's approach has an advantage: it uses actual native components, so
+updates to iOS or Android automatically apply to React Native apps. But this
+same characteristic creates consistency problems. Your React Native app can look
+and behave differently depending on the OS version. Flutter trades this
+automatic updating for guaranteed consistency across platforms and OS versions.
+
+### Flutter vs. Native Development
+
+Building native apps in Swift and Kotlin gives you immediate access to every OS
+API and the latest platform features on day one. Flutter catches up quickly
+(usually within weeks of a platform update), but native development is always
+first to new capabilities.
+
+The tradeoff is the maintenance burden. Native development means maintaining
+separate codebases with duplicated business logic, separate testing, and
+coordinated releases. For teams that can't afford dedicated iOS and Android
+engineers, or for companies where mobile isn't the core product, this
+duplication is expensive. Flutter significantly reduces this maintenance cost,
+though you give up the cutting edge of platform features.
+
+The decision often comes down to your constraints. If you need the absolute
+latest iOS 26 features and your app's value is tied to platform-specific
+capabilities, native development makes sense. If you need to ship across
+platforms quickly, control your interface precisely, and minimize long-term
+maintenance, Flutter is the better choice.
+
+## Where Shorebird Fits in the Stack
+
+The app stores serve a purpose. They enforce security standards, review apps for
+policy compliance, and give users confidence about the software they install.
+But the review process creates a bottleneck. You can't respond to production
+issues quickly. You can't iterate based on user feedback without waiting days
+for approval.
+
+This is the "last mile" problem. Flutter solves the problem of writing once and
+deploying everywhere. But you still hit the bottleneck of app store review times
+when you need to update your app.
+
+[Shorebird patches this last mile](https://docs.shorebird.dev/code-push/system-architecture/).
+It enables over-the-air updates that bypass the store review process. When you
+find a bug, you [create a patch](https://docs.shorebird.dev/code-push/patch/)
+and push it directly to your users. They receive the update automatically,
+without reinstalling your app or waiting for store approval. Shorebird works by
+separating your Dart code from your native app shell. The shell (which contains
+platform-specific code) goes through normal store reviews. Your Dart code (which
+is most of your app) can be updated over-the-air.
+
+Shorebird integrates cleanly with the rest of the Flutter ecosystem. You can add
+Shorebird commands to your
+[Codemagic workflows](https://docs.shorebird.dev/code-push/ci/codemagic/) to
+automatically create patches when you merge to production. Your developers
+continue using their existing tools. Shorebird adds one command to your
+[deployment process](https://docs.shorebird.dev/code-push/guides/development-workflow/).
+
+The philosophy behind Shorebird is that big tech companies like Google, Meta,
+and Microsoft have solved these problems internally for their own apps. They
+have systems to update apps without store reviews. Shorebird makes these
+capabilities available to every Flutter developer, not just teams with the
+resources to build their own infrastructure.
+
+## Next Steps
+
+Now that you understand Flutter and the ecosystem around it, here are practical
+paths forward:
+
+**Start Your First Flutter Project**: Download the
+[Flutter SDK](https://docs.flutter.dev/get-started/install) and follow the
+[Shorebird Quick Start](https://docs.shorebird.dev/getting-started/) to create a
+new project with code push capabilities built in. The `shorebird create` command
+scaffolds a Flutter app with Shorebird already integrated.
+
+**Set Up Your Development Workflow**: Establish a robust development process by
+following Shorebird's
+[development workflow guide](https://docs.shorebird.dev/code-push/guides/development-workflow/).
+Learn how to
+[test patches](https://docs.shorebird.dev/code-push/guides/testing-patches/)
+before deploying them and implement
+[staging environments](https://docs.shorebird.dev/code-push/guides/staging-patches/)
+to catch issues before production.
+
+**Implement Continuous Integration**: Automate your build and deployment
+pipeline using
+[Shorebird's CI documentation](https://docs.shorebird.dev/code-push/ci/github/).
+Whether you're using GitHub Actions,
+[Codemagic](https://docs.shorebird.dev/code-push/ci/codemagic/), or
+[Fastlane](https://docs.shorebird.dev/code-push/ci/fastlane/), you can integrate
+code push into your existing workflows.
+
+**Prepare for Production Release**: Before launching to the app stores, review
+the platform-specific guidelines for
+[iOS](https://docs.shorebird.dev/code-push/guides/stores/app-store/) and
+[Android](https://docs.shorebird.dev/code-push/guides/stores/play-store/).
+Implement
+[patch signing](https://docs.shorebird.dev/code-push/guides/patch-signing/) for
+additional security and set up
+[percentage-based rollouts](https://docs.shorebird.dev/code-push/guides/percentage-based-rollouts/)
+to gradually deploy updates to your user base.
+
+**Scale Your Team's Usage**: If you're working with a team, set up
+[Shorebird Organizations](https://docs.shorebird.dev/account/orgs/) to manage
+access and collaborate on releases. Configure your apps to work with
+[build flavors](https://docs.shorebird.dev/code-push/guides/flavors/android/) if
+you maintain multiple app variants or white-label applications.

src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx

@@ -1,8 +1,8 @@
 ---
 title: Flutter SDK Deep Dive
-description: Learn how to manage organizations in Shorebird
+description: Learn how the Flutter SDK works under the covers
 sidebar:
-  order: 1
+  order: 2
 ---
 
 This article is a technical deep-dive through various parts of Flutter, written