How namma-flutter/namma_wallet works
1. Product shape
- Namma Wallet is a Flutter cross-platform app for managing travel-related tickets and passes.
- The core user value is not ticket purchase; it is ingestion, parsing, storage, presentation, and sharing of ticket data from multiple formats.
2. Primary app boundary
- The Flutter app lives in lib/ and is organized as a feature-based architecture with a shared common/ layer.
- lib/main.dart bootstraps the app, while lib/src/app.dart is the main composition root that wires navigation, theme, and global services.
3. Shared platform and app infrastructure
- lib/src/common/ holds the cross-cutting subsystems: database access, routing, DI, logging, theming, utilities, OCR, PDF, widget sync, haptics, and shared UI.
- This layer is the main architectural boundary between reusable infrastructure and feature-specific business logic.
4. Persistence layer
- Ticket and user data are abstracted behind DAO and database interfaces in lib/src/common/database/.
- There are platform-specific database implementations for mobile and web, which is important for diagramming the storage boundary: the app can persist data locally on device and also support a web-backed storage path.
- The database layer feeds most downstream views, including home, calendar, export, and widgets.
5. Ticket ingestion pipelines
- The app supports multiple input channels, each modeled as its own feature:
- import/ for file picker / deep link style imports
- receive/ for share-sheet inbound content
- clipboard/ for pasted ticket text
- irctc/, tnstc/, and travel/ for domain-specific parsing
- ai/ fallback parsing for less structured content
- These pipelines all converge into normalized domain models that the rest of the app can render and store.
6. Domain normalization
- Shared domain entities such as ticket, user, extras_model, tag_model, and the various enums live under lib/src/common/domain/.
- Feature modules also define their own normalized models, such as travel_model, tnstc_model, irctc_ticket_model, and event_model.
- The architecture depends heavily on mapping raw inputs into these domain objects before UI or persistence handles them.
7. Parsing and extraction services
- The most important backend-like logic in this repo is local parsing:
- travel/ handles .pkpass, PDFs, and SMS-derived travel tickets
- irctc/ handles SMS, QR, layout parsing, and scanner coordination
- tnstc/ handles API, layout, and SMS parsing plus PNR fetch
- common/services/ocr/ contains OCR abstractions with mobile and web implementations
- These are pure app-side extraction pipelines, not remote backend services, except where TNSTC PNR lookup or pass web-service refresh is explicitly required.
8. Presentation layer
- UI is feature-scoped under each feature’s presentation/ directory, with views like home_view, all_tickets_view, ticket_view, calendar_view, settings_view, and import/share screens.
- Reusable UI components are centralized in common/widgets/ and feature-local widget folders.
- The UI is structured around the ticket lifecycle: ingest → normalize → persist → browse → inspect.
9. Navigation and app state
- Routing is handled centrally in common/routing/ via app routes and a router setup.
- Global state/services are coordinated through the locator in common/di/locator.dart and change-notifier style services such as ticket_change_notifier.
- This suggests a fairly classic Flutter composition model where feature views react to shared app state rather than owning isolated stores.
10. Platform integrations
- Native integration is material to the architecture:
- android/ includes the main activity plus home-screen widget providers/services for ticket widgets.
- ios/ includes the runner app, a Share Extension, and a TicketWidget extension.
- The app is therefore not only an in-app UI; it also exposes functionality through OS surfaces like share sheets and widgets.
11. Cross-platform feature differences
- Several services have explicit mobile vs web variants, such as platform DB, widget services, OCR, deep link handling, sharing intent handling, and Gemma/AI fallback services.
- This is a key diagram boundary: shared feature interfaces remain stable while platform-specific implementations diverge behind them.
12. External file/format dependencies
- The app handles a variety of external content types and formats: SMS text, PDF documents, QR codes, Apple Wallet .pkpass files, clipboard text, and deep links.
- The repo also includes web/ assets for PDF/WASM support, showing that PDF parsing and rendering are first-class concerns, not incidental UI details.
13. Supporting tooling and release pipeline
- The repo includes substantial build/release automation: Makefile, Fastlane for Android/iOS, GitHub Actions, Flutter analysis/linting, and platform-specific checks.
- Release builds intentionally run code generation and remove WASM modules for pdfrx, which affects artifact size and packaging flow.
- This matters architecturally because the build pipeline is part of how the app’s parsing and rendering stack is made shippable across platforms.
14. Test strategy
- The test/ tree is broad and feature-aligned, with fixtures for IRCTC, TNSTC, and pkpass parsing, plus fakes for database, router, logger, and services.
- This indicates the repo’s highest-risk logic is the parsing and normalization pipeline, and tests are designed to validate those transformations in isolation from the UI.
15. How to draw the architecture
- The clearest diagram is: Input sources and native OS surfaces on the left, feature-specific parsers/services in the middle, shared domain + persistence below, and presentation/navigation on the right.
- Add a separate boundary for platform-specific implementations (mobile/web, Android/iOS extensions, widget services) hanging off the shared interfaces.
Main entry points: wallet_database.dart Wallet DB · travel_parser_service.dart Travel parser · ticket.dart Domain models · app.dart App root
Components 22
App shell
Flutter entrypoint, composition root, routing, theme, and global state.
- main.dart · App entrypoint that boots the Flutter runtime.
lib/main.dart - App root · Main app wiring for navigation, theme, and global services.
lib/src/app.dart - Router · Central route definitions and router setup.
lib/src/common/routing/app_router.dart - Locator · Global dependency injection and shared service resolution.
lib/src/common/di/locator.dart - Theme · App theme, colors, fonts, and theme provider.
lib/src/common/theme/app_theme.dart
Shared core
Cross-cutting infrastructure, persistence, services, and shared domain.
- Wallet DB · Database abstraction and DAOs for tickets and users.
lib/src/common/database/wallet_database.dart - Domain models · Shared ticket, user, extras, tags, and enums used across the app.
lib/src/common/domain/models/ticket.dart - Logger · Shared logging abstraction and implementation.
lib/src/common/services/logger/namma_logger.dart - OCR · OCR abstractions with mobile and web implementations for text extraction.
lib/src/common/services/ocr/ocr_service_interface.dart - PDF · PDF service used by import and ticket parsing flows.
lib/src/common/services/pdf/pdf_service_interface.dart
Feature pipelines
Inbound parsing, normalization, and feature UI surfaces.
- Travel parser · Parses PKPass, PDF, and SMS-based travel tickets.
lib/src/features/travel/application/travel_parser_service.dart - IRCTC parser · Handles IRCTC SMS, QR, layout, and scanner-based extraction.
lib/src/features/irctc/application/irctc_sms_parser.dart - TNSTC parser · Parses TNSTC API, layout, and SMS inputs plus PNR fetch.
lib/src/features/tnstc/application/tnstc_api_ticket_parser.dart - AI fallback · Gemma-based fallback parsing for less structured content.
lib/src/features/ai/fallback_parser/application/gemma_service.dart - Import flow · File, deep-link, and import entry path for ticket ingestion.
lib/src/features/import/application/import_service.dart - Share receive · Inbound share-sheet content processing and handoff.
lib/src/features/receive/application/shared_content_processor.dart - Clipboard · Pasted text ingestion for ticket extraction.
lib/src/features/clipboard/application/clipboard_service.dart - Home UI · Home, all tickets, and ticket inspection surfaces.
lib/src/features/home/presentation/home_view.dart - Calendar UI · Calendar view for browsing tickets by date.
lib/src/features/calendar/presentation/calendar_view.dart - Settings UI · Settings, diagnostics, licenses, and status screens.
lib/src/features/settings/presentation/settings_view.dart
Platform surfaces
Android, iOS, and web-specific integrations and implementations.
- Platform DB · Mobile and web database implementations behind a shared interface.
lib/src/common/database/platform/platform_db.dart - Widget sync · Home-widget integration for ticket previews and updates.
lib/src/common/services/widget/widget_service_interface.dart
Connections 23
- main.dart → App root: boots · Entrypoint initializes the app root.
- App root → Router: uses · App root wires navigation.
- App root → Locator: configures · App root registers and resolves shared services.
- App root → Theme: applies · App root sets the visual theme.
- Locator → Wallet DB: provides · Service locator exposes persistence and feature services.
- Wallet DB → Platform DB: backed by · Shared database interface delegates to mobile or web implementation.
- Wallet DB → Domain models: stores · Database layer persists normalized domain entities.
- Travel parser → Domain models: normalizes to · Travel inputs are mapped into shared domain models.
- IRCTC parser → Domain models: normalizes to · IRCTC inputs are mapped into shared domain models.
- TNSTC parser → Domain models: normalizes to · TNSTC inputs are mapped into shared domain models.
- AI fallback → Domain models: normalizes to · Fallback parsing produces normalized ticket data.
- Import flow → Travel parser: routes to · Import flow hands file or link payloads to parsers.
- Share receive → AI fallback: falls back to · Shared content can be routed to AI fallback parsing.
- Clipboard → Travel parser: feeds · Clipboard text is parsed through the ticket pipeline.
- Travel parser → OCR: uses · Travel parsing can extract text from images and PDFs.
- Travel parser → PDF: uses · Travel parsing depends on PDF handling.
- IRCTC parser → OCR: uses · IRCTC layout parsing depends on OCR extraction.
- TNSTC parser → PDF: uses · TNSTC parsing uses PDF extraction.
- Home UI → Wallet DB: reads · Home and ticket views consume persisted ticket data.
- Calendar UI → Wallet DB: reads · Calendar browse state is derived from stored tickets.
- Settings UI → Logger: shows · Settings surfaces diagnostics and runtime status.
- Widget sync → Wallet DB: reads · Widget updates are driven by persisted ticket data.
- Platform DB → Widget sync: supports · Platform storage and widget surfaces are part of the same local boundary.