ashok-a15/ai_story_buddy

1. Overall shape

This is a cross-platform Flutter app with one primary product flow: a single story-reading screen that narrates a short story, then transitions into an interactive quiz. The business logic is concentrated in Dart under lib/, while android/, ios/, macos/, linux/, windows/, and web/ are mostly standard Flutter host shells.

2. Primary feature boundary

The app is organized as a feature-centric mini-application rather than a multi-module product. The core feature lives in lib/screens/story_screen.dart, supported by a small set of state, model, service, utility, and widget files. This makes the story/quiz experience the central architectural unit.

3. State management spine

lib/providers/story_provider.dart is the main orchestration layer. The README indicates this uses Riverpod with an immutable notifier/state pair (StoryNotifier + StoryStateData) as the single source of truth. That state drives the screen’s progression through idle, loading, playing, quiz, success, and error-like conditions.

4. Narration service boundary

Text-to-speech is encapsulated in lib/services/tts_service.dart. This is the app’s main service boundary and wraps the flutter_tts plugin. The service is responsible for narration lifecycle events such as start, completion, and error, while the provider reacts to those callbacks and updates UI state.

5. Data-driven quiz layer

lib/models/quiz_model.dart defines the quiz data contract. The quiz is not hardcoded as fixed UI text; it is parsed from JSON and rendered dynamically, allowing question text and option count to vary without changing layout code. This is the main data model feeding the quiz phase.

6. Presentation composition

The UI is split into small reusable widgets under lib/widgets/: story_card, quiz_card, answer_option, primary_button, and buddy_character. These form the screen’s visual building blocks and are composed by story_screen.dart. The buddy_character widget is especially important because Pip is the animated narrative companion and visual feedback anchor.

7. Flow of control

The user experience follows a simple event pipeline: the child taps the story button, the provider moves into a loading/narration state, the TTS service speaks the story, and on completion the UI switches to the quiz card. Selecting an answer updates the provider again, which drives either a success celebration or a retry path.

8. Visual and interaction styling

lib/utils/theme.dart and lib/utils/constants.dart centralize shared styling and app-wide values. The design is themed for children with soft gradients, rounded cards, and playful interaction cues. The architecture suggests the app relies on declarative widget state rather than imperative screen navigation.

9. Platform integration

The native platform folders are mostly boilerplate Flutter runners, but they still matter architecturally because they host the plugin registrations and app entry points for each target OS. On Android and iOS, the app starts through the generated Flutter embedding and then immediately hands control to the Dart app. No custom native business logic appears in the tree.

10. Testing and quality boundaries

There is a small widget test suite in test/widget_test.dart plus platform-specific runner tests in iOS/macOS. This indicates the app is tested primarily at the UI/widget level rather than through a large service or backend test surface. The README also calls out animation/test safeguards to avoid hanging tests.

11. External dependencies that affect architecture

The only materially important external runtime dependency called out in the README is Flutter TTS. It directly shapes the app flow because narration completion determines when the quiz appears. Riverpod is the other key architectural dependency because it owns state transitions and UI updates.

12. What is not present

There is no obvious server, database, authentication system, or multi-screen navigation structure in the repository tree. Architecturally, this is a self-contained client app: one screen, one state machine, one narration service, one dynamic quiz model, and a set of presentation widgets built around them.