Project · Flutter and Dart
Project: a PIN code finder for a courier desk
The brief
Build PIN Finder, a Flutter app for a courier counter: type a 6-digit PIN code, load its post offices from the India Post API, see which ones deliver, keep recent searches on the device, and use one pane on phones and two on wide screens. Prove it with unit, widget and integration tests, then build it for Android and the web.
Why it matters
Courier, e-commerce and logistics apps check PIN codes all day. This project has everything an expert Flutter job asks for: a real HTTP API and JSON parsing, offline-friendly local storage, smooth animations, a layout that works on a counter's desktop and a rider's phone, a full test pyramid, and release builds.
Skills you practise
- http with an injected Client and MockClient
- jsonDecode and Dart 3 patterns on JSON
- sealed classes for UI state
- shared_preferences
- Provider and ChangeNotifier
- AnimatedSwitcher and AnimatedContainer
- LayoutBuilder breakpoints
- unit, widget and integration tests
- flutter build apk, appbundle and web
You need
- Flutter 3.24 or newer (stable), with Android Studio or VS Code
- An Android emulator or phone, and Chrome for the web build
- An internet connection to call https://api.postalpincode.in (a free public API; it can be slow, which is why the tests use a fake)
What you will have at the end
The PIN Finder app: real API calls with JSON parsing and error handling, recent searches stored on the device, animated results, a phone and wide-screen layout, 12 unit and widget tests plus an integration test, and release builds for Android (APK and AAB) and the web.
How it is marked (rubric, 100 points)
| Data layerThe API client validates input, times out, handles non-200 replies and odd JSON, and is tested with MockClient; recent searches are stored and tested. | 25 |
|---|---|
| UI, state and motionA sealed state drives the screen; loading, empty, error and data each look right; results animate; the layout switches at 840 px. | 25 |
| TestingAll 12 unit and widget tests and the integration test pass; tests use fakes, never the live API. | 25 |
| Release readyflutter analyze is clean; the APK, AAB and web builds succeed; the INTERNET permission is set; the README notes CORS for the web. | 25 |
0/8 steps done
Step 1 of 8
The JSON model
parsePinResponse turns the API's JSON into PinFound or PinNotFound, and test/models_test.dart passes.
Create the project (flutter create --org com.example pin_finder) and add the packages: flutter pub add http shared_preferences provider. Copy the starter files and delete test/widget_test.dart.
The API returns a JSON list with one object. When Status is 'Success', PostOffice is a list of offices; otherwise it is null. Use an if-case with a list pattern to check the shape and bind the list in one go: if (data case [{'Status': 'Success', 'PostOffice': List offices}, ...]). Anything else, including a body you did not expect, is PinNotFound: never let a surprising response crash the app. In PostOffice.fromJson, read each field with as String?, give defaults with ??, and set delivery to DeliveryStatus == 'Delivery'.
$ flutter test --reporter expanded test/models_test.dartAlso check yourself
Your notes: lib/models.dart, lib/pin_api.dart, lib/recent_store.dart, lib/main.dart
Write down each command you ran. It goes into your project summary.