# namma-flutter/namma_wallet architecture

> Architecture diagram of the GitHub repository namma-flutter/namma_wallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/namma-flutter/namma_wallet
- Repository: https://github.com/namma-flutter/namma_wallet

## Overview

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: [`lib/src/common/database/wallet_database.dart`](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/database/wallet_database.dart) (Wallet DB), [`lib/src/features/travel/application/travel_parser_service.dart`](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/travel/application/travel_parser_service.dart) (Travel parser), [`lib/src/common/domain/models/ticket.dart`](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/domain/models/ticket.dart) (Domain models), [`lib/src/app.dart`](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/app.dart) (App root)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_lib_main(("main.dart<br/>Flutter entry<br/>[main.dart]"))
  node_lib_app["App root<br/>composition root<br/>[app.dart]"]
  node_router["Router<br/>navigation<br/>[app_router.dart]"]
  node_locator["Locator<br/>service registry<br/>[locator.dart]"]
  node_theme["Theme<br/>ui styling<br/>[app_theme.dart]"]
end

subgraph group_group_common["Shared core"]
  node_wallet_db[("Wallet DB<br/>persistence interface")]
  node_domain_models["Domain models<br/>normalized entities<br/>[ticket.dart]"]
  node_logger["Logger<br/>observability<br/>[namma_logger.dart]"]
  node_ocr["OCR<br/>extraction service"]
  node_pdf["PDF<br/>document service"]
end

subgraph group_group_features["Feature pipelines"]
  node_travel_parser["Travel parser<br/>format parser"]
  node_irctc_parser["IRCTC parser<br/>format parser"]
  node_tnstc_parser["TNSTC parser<br/>format parser"]
  node_ai_fallback["AI fallback<br/>fallback parser<br/>[gemma_service.dart]"]
  node_import_flow["Import flow<br/>ingestion feature"]
  node_receive_flow["Share receive<br/>ingestion feature"]
  node_clipboard_flow["Clipboard<br/>ingestion feature"]
  node_home_ui["Home UI<br/>presentation<br/>[home_view.dart]"]
  node_calendar_ui["Calendar UI<br/>presentation<br/>[calendar_view.dart]"]
  node_settings_ui["Settings UI<br/>presentation<br/>[settings_view.dart]"]
end

subgraph group_group_platform["Platform surfaces"]
  node_platform_db[("Platform DB<br/>storage backend<br/>[platform_db.dart]")]
  node_widget_sync["Widget sync<br/>sync service"]
end

node_lib_main -->|"boots"| node_lib_app
node_lib_app -->|"uses"| node_router
node_lib_app -->|"configures"| node_locator
node_lib_app -->|"applies"| node_theme
node_locator -->|"provides"| node_wallet_db
node_wallet_db -->|"backed by"| node_platform_db
node_wallet_db -->|"stores"| node_domain_models
node_travel_parser -->|"normalizes to"| node_domain_models
node_irctc_parser -->|"normalizes to"| node_domain_models
node_tnstc_parser -->|"normalizes to"| node_domain_models
node_ai_fallback -->|"normalizes to"| node_domain_models
node_import_flow -->|"routes to"| node_travel_parser
node_receive_flow -->|"falls back to"| node_ai_fallback
node_clipboard_flow -->|"feeds"| node_travel_parser
node_travel_parser -->|"uses"| node_ocr
node_travel_parser -->|"uses"| node_pdf
node_irctc_parser -->|"uses"| node_ocr
node_tnstc_parser -->|"uses"| node_pdf
node_home_ui -->|"reads"| node_wallet_db
node_calendar_ui -->|"reads"| node_wallet_db
node_settings_ui -->|"shows"| node_logger
node_widget_sync -->|"reads"| node_wallet_db
node_platform_db -->|"supports"| node_widget_sync

click node_lib_main "https://github.com/namma-flutter/namma_wallet/blob/main/lib/main.dart"
click node_lib_app "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/app.dart"
click node_router "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/routing/app_router.dart"
click node_locator "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/di/locator.dart"
click node_theme "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/theme/app_theme.dart"
click node_wallet_db "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/database/wallet_database.dart"
click node_platform_db "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/database/platform/platform_db.dart"
click node_domain_models "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/domain/models/ticket.dart"
click node_logger "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/logger/namma_logger.dart"
click node_ocr "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/ocr/ocr_service_interface.dart"
click node_pdf "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/pdf/pdf_service_interface.dart"
click node_widget_sync "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/widget/widget_service_interface.dart"
click node_travel_parser "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/travel/application/travel_parser_service.dart"
click node_irctc_parser "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/irctc/application/irctc_sms_parser.dart"
click node_tnstc_parser "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/tnstc/application/tnstc_api_ticket_parser.dart"
click node_ai_fallback "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/ai/fallback_parser/application/gemma_service.dart"
click node_import_flow "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/import/application/import_service.dart"
click node_receive_flow "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/receive/application/shared_content_processor.dart"
click node_clipboard_flow "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/clipboard/application/clipboard_service.dart"
click node_home_ui "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/home/presentation/home_view.dart"
click node_calendar_ui "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/calendar/presentation/calendar_view.dart"
click node_settings_ui "https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/settings/presentation/settings_view.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib_main,node_lib_app,node_router,node_locator,node_theme toneBlue
class node_wallet_db,node_domain_models,node_logger,node_ocr,node_pdf toneAmber
class node_travel_parser,node_irctc_parser,node_tnstc_parser,node_ai_fallback,node_import_flow,node_receive_flow,node_clipboard_flow,node_home_ui,node_calendar_ui,node_settings_ui toneMint
class node_platform_db,node_widget_sync toneRose
```

## Components

### App shell

Flutter entrypoint, composition root, routing, theme, and global state.

- [main.dart](https://github.com/namma-flutter/namma_wallet/blob/main/lib/main.dart): Flutter entry · App entrypoint that boots the Flutter runtime. · `lib/main.dart`
- [App root](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/app.dart): composition root · Main app wiring for navigation, theme, and global services. · `lib/src/app.dart`
- [Router](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/routing/app_router.dart): navigation · Central route definitions and router setup. · `lib/src/common/routing/app_router.dart`
- [Locator](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/di/locator.dart): service registry · Global dependency injection and shared service resolution. · `lib/src/common/di/locator.dart`
- [Theme](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/theme/app_theme.dart): ui styling · 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](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/database/wallet_database.dart): persistence interface · Database abstraction and DAOs for tickets and users. · `lib/src/common/database/wallet_database.dart`
- [Domain models](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/domain/models/ticket.dart): normalized entities · Shared ticket, user, extras, tags, and enums used across the app. · `lib/src/common/domain/models/ticket.dart`
- [Logger](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/logger/namma_logger.dart): observability · Shared logging abstraction and implementation. · `lib/src/common/services/logger/namma_logger.dart`
- [OCR](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/ocr/ocr_service_interface.dart): extraction service · OCR abstractions with mobile and web implementations for text extraction. · `lib/src/common/services/ocr/ocr_service_interface.dart`
- [PDF](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/pdf/pdf_service_interface.dart): document service · 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](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/travel/application/travel_parser_service.dart): format parser · Parses PKPass, PDF, and SMS-based travel tickets. · `lib/src/features/travel/application/travel_parser_service.dart`
- [IRCTC parser](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/irctc/application/irctc_sms_parser.dart): format parser · Handles IRCTC SMS, QR, layout, and scanner-based extraction. · `lib/src/features/irctc/application/irctc_sms_parser.dart`
- [TNSTC parser](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/tnstc/application/tnstc_api_ticket_parser.dart): format parser · Parses TNSTC API, layout, and SMS inputs plus PNR fetch. · `lib/src/features/tnstc/application/tnstc_api_ticket_parser.dart`
- [AI fallback](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/ai/fallback_parser/application/gemma_service.dart): fallback parser · Gemma-based fallback parsing for less structured content. · `lib/src/features/ai/fallback_parser/application/gemma_service.dart`
- [Import flow](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/import/application/import_service.dart): ingestion feature · File, deep-link, and import entry path for ticket ingestion. · `lib/src/features/import/application/import_service.dart`
- [Share receive](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/receive/application/shared_content_processor.dart): ingestion feature · Inbound share-sheet content processing and handoff. · `lib/src/features/receive/application/shared_content_processor.dart`
- [Clipboard](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/clipboard/application/clipboard_service.dart): ingestion feature · Pasted text ingestion for ticket extraction. · `lib/src/features/clipboard/application/clipboard_service.dart`
- [Home UI](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/home/presentation/home_view.dart): presentation · Home, all tickets, and ticket inspection surfaces. · `lib/src/features/home/presentation/home_view.dart`
- [Calendar UI](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/calendar/presentation/calendar_view.dart): presentation · Calendar view for browsing tickets by date. · `lib/src/features/calendar/presentation/calendar_view.dart`
- [Settings UI](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/features/settings/presentation/settings_view.dart): presentation · 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](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/database/platform/platform_db.dart): storage backend · Mobile and web database implementations behind a shared interface. · `lib/src/common/database/platform/platform_db.dart`
- [Widget sync](https://github.com/namma-flutter/namma_wallet/blob/main/lib/src/common/services/widget/widget_service_interface.dart): sync service · Home-widget integration for ticket previews and updates. · `lib/src/common/services/widget/widget_service_interface.dart`

## Connections

- 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.
