# pixelweavedev/step_up_fuels architecture

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

- Interactive diagram: https://gitdiagram.com/pixelweavedev/step_up_fuels
- Repository: https://github.com/pixelweavedev/step_up_fuels

## Overview

1. **What this repo is**
   - `step_up_fuels` is a multi-platform Flutter app for fuel-station operations management.
   - The codebase is organized as an **offline-first, local-data business system** rather than a client/server app: there is no backend service code in the repo, and most business operations persist to an embedded local database.

2. **Top-level architecture style**
   - The app follows a **layered / clean-architecture-style structure**:
     - `presentation` for screens and state providers
     - `application` for use cases
     - `domain` for entities, repository contracts, and business services
     - `data` for database tables, DAOs, mappers, and repository implementations
   - Shared, cross-cutting code lives in `lib/core` and reusable UI in `lib/shared`.

3. **Runtime and platform boundaries**
   - Flutter targets **Android, iOS, web, and Windows** from the same Dart codebase.
   - Native folders are present only as platform shells; the real product logic lives in `lib/`.
   - The presence of generated `*.g.dart` files alongside tables/DAOs strongly suggests a code-generated local persistence layer, likely using an embedded ORM such as Drift.

4. **Central composition layer**
   - `lib/main.dart` boots the app.
   - `lib/app/app.dart` is the root application widget.
   - `lib/app/di/injection_container.dart` wires dependencies.
   - `lib/app/router/app_router.dart` and `route_names.dart` define navigation.
   - `lib/app/database/app_database.dart` is the main database entry point and the hub for all persistent modules.

5. **Core subsystems**
   - `lib/core` contains app-wide concerns:
     - constants for GST, UI, and other shared values
     - error and failure types
     - result handling
     - logging
     - theme, colors, and text styles
     - common extension methods and utilities
   - This layer is intentionally dependency-light and supports all feature modules.

6. **State and UI composition**
   - Each feature has a `presentation/providers` layer and a `presentation/screens` layer.
   - Shared widgets such as scaffold, sidebar, buttons, dialogs, inputs, loading overlay, and stat cards live under `lib/shared/widgets`.
   - The UI appears to be desktop/tablet friendly as well as mobile-friendly, with a reusable sidebar-based app shell.

7. **Feature module pattern**
   - Most business domains are split into the same three internal layers:
     - `domain`: entities and repository interfaces
     - `application`: use cases for commands and queries
     - `data`: persistence tables, DAOs, mappers, repository implementations
   - This pattern is repeated across customers, drivers, expenses, inventory, invoices, ledger, payments, products, purchases, reports, settings, and vehicles.

8. **Data model and persistence**
   - Persistent data is modeled per feature using dedicated tables, for example:
     - `customers_*`, `invoices_*`, `purchases_*`, `payments_*`, `vehicles_*`, `ledger_*`, `inventory_*`
   - DAOs sit on top of these tables and repositories wrap the DAOs for the rest of the app.
   - Mappers convert between database records and domain entities, keeping the UI/business layer isolated from storage details.

9. **Main business flows**
   - **Billing/invoicing**: invoices and line items, cancel/save/post actions, GST calculations, and invoice printing/reporting support.
   - **Purchases and expenses**: supplier management, fuel purchase recording, payment status updates, and expense entry.
   - **Inventory**: stock levels, movements, storage locations, adjustments, and reconciliation.
   - **Vehicles and drivers**: vehicle records, service records, driver records, and assignment tracking.
   - **Customers**: customer profiles with contacts, sites, notes, documents, and credit limits.
   - **Payments and ledger**: payment records and accounting-style ledger entries/accounts.

10. **Cross-module dependencies**
   - Several features are intentionally interconnected:
     - invoices depend on customers, products, settings, GST logic, and payments/ledger reporting
     - purchases affect inventory and may link to expenses and payment status
     - dashboard and reports aggregate data from many modules rather than owning data themselves
   - This makes `reports`, `dashboard`, and `ledger` important integration points in the architecture.

11. **Reporting and document generation**
   - `lib/features/reports` includes exporters for **Excel** and **PDF**, plus a reporting service.
   - The presence of sample invoice `.docx` and `.pdf` files indicates document generation/formatting is a real part of the product boundary, not just a UI concern.

12. **Settings, compliance, and access control**
   - `settings` stores company profile, invoice settings, print settings, and document/user-related tables.
   - Documentation in `Docs/09_GST_Compliance.md` and `Docs/11_RBAC.md` shows the app is designed around **GST compliance** and **role-based access control**, even if those concerns are only partially visible in the code tree.
   - `Docs/12_Future_SaaS.md` suggests a roadmap toward SaaS, but the current architecture is still primarily single-app/local-storage oriented.

13. **Testing and validation**
   - The `test/` folder contains integration-style domain tests for major flows such as:
     - database behavior
     - payments/ledger
     - purchases/expenses
     - reports/dashboard
     - settings
     - vehicle/driver workflows
   - This indicates the system is validated around business rules and module interactions, not just widgets.

14. **Architecture summary for a diagram**
   - A good diagram should show:
     - a Flutter UI shell on top
     - feature-specific presentation providers/screens
     - use case/application services in the middle
     - repositories and DAOs below
     - a shared local database at the bottom
     - cross-cutting core/shared layers beside the feature stack
   - The most important arrows are from UI to use cases to repositories to the database, plus lateral aggregation arrows into dashboard and reporting.

Main entry points: [`lib/app/di/injection_container.dart`](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/di/injection_container.dart) (DI container), [`lib/features/invoices`](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/invoices) (Invoices), [`lib/features/dashboard`](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/dashboard) (Dashboard), [`lib/features/customers`](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/customers) (Customers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_main["main<br/>Flutter entrypoint<br/>[main.dart]"]
  node_app_widget["App<br/>Root widget<br/>[app.dart]"]
  node_injector["DI container<br/>Dependency wiring"]
  node_router["Router<br/>Navigation<br/>[app_router.dart]"]
  node_database[("App DB<br/>Local database<br/>[app_database.dart]")]
end

subgraph group_group_core["Core & Shared"]
  node_core["Core<br/>Shared utilities"]
  node_shared_ui["Shared UI<br/>Reusable widgets"]
end

subgraph group_group_features["Feature Modules"]
  node_dashboard["Dashboard<br/>Aggregator"]
  node_customers["Customers<br/>Feature module"]
  node_invoices["Invoices<br/>Billing module"]
  node_purchases["Purchases<br/>Procurement module"]
  node_inventory["Inventory<br/>Stock module"]
  node_vehicles["Vehicles<br/>Fleet module"]
  node_drivers["Drivers<br/>Fleet module"]
  node_payments["Payments"]
  node_ledger["Ledger<br/>Accounting module"]
  node_reports["Reports<br/>Exporting module"]
  node_settings["Settings<br/>Configuration module"]
end

subgraph group_group_platform["Platform Shells"]
  node_android["Android<br/>Platform shell"]
  node_ios["iOS<br/>Platform shell"]
  node_web["Web<br/>Platform shell"]
  node_windows["Windows<br/>Platform shell"]
end

node_main -->|"boots"| node_app_widget
node_app_widget -->|"initializes"| node_injector
node_app_widget -->|"navigates"| node_router
node_injector -->|"configures"| node_database
node_injector -->|"wires"| node_customers
node_injector -->|"wires"| node_invoices
node_injector -->|"wires"| node_purchases
node_injector -->|"wires"| node_inventory
node_injector -->|"wires"| node_payments
node_injector -->|"wires"| node_ledger
node_injector -->|"wires"| node_reports
node_customers -->|"persists"| node_database
node_invoices -->|"uses"| node_customers
node_invoices -->|"uses"| node_payments
node_invoices -->|"uses"| node_ledger
node_invoices -->|"uses"| node_settings
node_purchases -->|"updates"| node_inventory
node_purchases -->|"uses"| node_payments
node_inventory -->|"persists"| node_database
node_vehicles -->|"links"| node_drivers
node_reports -->|"aggregates"| node_dashboard
node_dashboard -->|"reads"| node_customers
node_dashboard -->|"reads"| node_invoices
node_dashboard -->|"reads"| node_purchases
node_dashboard -->|"reads"| node_inventory
node_dashboard -->|"reads"| node_payments
node_reports -->|"reads"| node_database
node_shared_ui -->|"supports"| node_customers
node_shared_ui -->|"supports"| node_invoices
node_core -->|"supports"| node_customers
node_core -->|"supports"| node_invoices
node_core -->|"supports"| node_reports

click node_main "https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/main.dart"
click node_app_widget "https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/app.dart"
click node_injector "https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/di/injection_container.dart"
click node_router "https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/router/app_router.dart"
click node_database "https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/database/app_database.dart"
click node_core "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/core"
click node_shared_ui "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/shared"
click node_dashboard "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/dashboard"
click node_customers "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/customers"
click node_invoices "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/invoices"
click node_purchases "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/purchases"
click node_inventory "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/inventory"
click node_vehicles "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/vehicles"
click node_drivers "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/drivers"
click node_payments "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/payments"
click node_ledger "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/ledger"
click node_reports "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/reports"
click node_settings "https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/settings"
click node_android "https://github.com/pixelweavedev/step_up_fuels/tree/main/android"
click node_ios "https://github.com/pixelweavedev/step_up_fuels/tree/main/ios"
click node_web "https://github.com/pixelweavedev/step_up_fuels/tree/main/web"
click node_windows "https://github.com/pixelweavedev/step_up_fuels/tree/main/windows"

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_main,node_app_widget,node_injector,node_router,node_database toneBlue
class node_core,node_shared_ui toneAmber
class node_dashboard,node_customers,node_invoices,node_purchases,node_inventory,node_vehicles,node_drivers,node_payments,node_ledger,node_reports,node_settings toneMint
class node_android,node_ios,node_web,node_windows toneRose
```

## Components

### App Shell

Flutter entrypoint, root widget, routing, and dependency wiring.

- [main](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/main.dart): Flutter entrypoint · Bootstraps the application. · `lib/main.dart`
- [App](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/app.dart): Root widget · Top-level app widget and theme composition. · `lib/app/app.dart`
- [DI container](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/di/injection_container.dart): Dependency wiring · Assembles repositories, services, and use cases. · `lib/app/di/injection_container.dart`
- [Router](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/router/app_router.dart): Navigation · Defines routes and route names for the app. · `lib/app/router/app_router.dart`
- [App DB](https://github.com/pixelweavedev/step_up_fuels/blob/main/lib/app/database/app_database.dart): Local database · Central embedded database entry point for all persistent modules. · `lib/app/database/app_database.dart`

### Core & Shared

Cross-cutting utilities and reusable UI used by all feature modules.

- [Core](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/core): Shared utilities · App-wide constants, errors, logging, results, theme, and helpers. · `lib/core`
- [Shared UI](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/shared): Reusable widgets · Common scaffold, sidebar, dialogs, inputs, loaders, and cards. · `lib/shared`

### Feature Modules

Business domains implemented with presentation, application, domain, and data layers.

- [Dashboard](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/dashboard): Aggregator · Summarizes data across modules for the home view and reporting entry points. · `lib/features/dashboard`
- [Customers](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/customers): Feature module · Customer profiles, contacts, sites, credit limits, and customer lifecycle. · `lib/features/customers`
- [Invoices](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/invoices): Billing module · Invoice creation, posting, cancellation, invoice items, and GST calculation. · `lib/features/invoices`
- [Purchases](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/purchases): Procurement module · Fuel purchases, suppliers, purchase status, and related entry flows. · `lib/features/purchases`
- [Inventory](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/inventory): Stock module · Stock levels, movements, storage locations, adjustments, and reconciliation. · `lib/features/inventory`
- [Vehicles](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/vehicles): Fleet module · Vehicle records, service records, and assignment tracking. · `lib/features/vehicles`
- [Drivers](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/drivers): Fleet module · Driver records and driver assignment workflows. · `lib/features/drivers`
- [Payments](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/payments): Payments module · Payment records used by billing and purchase workflows. · `lib/features/payments`
- [Ledger](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/ledger): Accounting module · Ledger accounts and entries used for accounting-style reporting and integration. · `lib/features/ledger`
- [Reports](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/reports): Exporting module · Reporting service plus Excel and PDF exporters. · `lib/features/reports`
- [Settings](https://github.com/pixelweavedev/step_up_fuels/tree/main/lib/features/settings): Configuration module · Company profile, invoice settings, print settings, documents, and users tables. · `lib/features/settings`

### Platform Shells

Native platform wrappers around the shared Flutter runtime.

- [Android](https://github.com/pixelweavedev/step_up_fuels/tree/main/android): Platform shell · Native Android host for the shared Flutter app. · `android`
- [iOS](https://github.com/pixelweavedev/step_up_fuels/tree/main/ios): Platform shell · Native iOS host for the shared Flutter app. · `ios`
- [Web](https://github.com/pixelweavedev/step_up_fuels/tree/main/web): Platform shell · Web host and assets for the shared Flutter app. · `web`
- [Windows](https://github.com/pixelweavedev/step_up_fuels/tree/main/windows): Platform shell · Windows host for the shared Flutter app. · `windows`

## Connections

- main → App: boots · Application entrypoint creates the root app widget.
- App → DI container: initializes · Root widget relies on dependency injection setup.
- App → Router: navigates · App shell uses router for screen composition and navigation.
- DI container → App DB: configures · DI container wires the shared local database.
- DI container → Customers: wires · Feature dependencies are composed through DI.
- DI container → Invoices: wires · Feature dependencies are composed through DI.
- DI container → Purchases: wires · Feature dependencies are composed through DI.
- DI container → Inventory: wires · Feature dependencies are composed through DI.
- DI container → Payments: wires · Feature dependencies are composed through DI.
- DI container → Ledger: wires · Feature dependencies are composed through DI.
- DI container → Reports: wires · Feature dependencies are composed through DI.
- Customers → App DB: persists · Customer data is stored in the shared local database.
- Invoices → Customers: uses · Invoices depend on customer data.
- Invoices → Payments: uses · Billing flows interact with payment records.
- Invoices → Ledger: uses · Billing flows feed accounting-style ledger reporting.
- Invoices → Settings: uses · Invoice behavior depends on company and GST settings.
- Purchases → Inventory: updates · Purchases affect stock and inventory state.
- Purchases → Payments: uses · Purchase flows track payment status.
- Inventory → App DB: persists · Stock movements and reconciliations are stored locally.
- Vehicles → Drivers: links · Fleet workflows connect vehicles with driver assignments.
- Reports → Dashboard: aggregates · Reporting and dashboard surfaces summarize many modules.
- Dashboard → Customers: reads · Dashboard aggregates customer-related metrics.
- Dashboard → Invoices: reads · Dashboard aggregates billing metrics.
- Dashboard → Purchases: reads · Dashboard aggregates purchasing metrics.
- Dashboard → Inventory: reads · Dashboard aggregates inventory metrics.
- Dashboard → Payments: reads · Dashboard aggregates payment metrics.
- Reports → App DB: reads · Exports and reporting pull from the shared data store.
- Shared UI → Customers: supports · Reusable widgets back feature screens and dialogs.
- Shared UI → Invoices: supports · Reusable widgets back feature screens and dialogs.
- Core → Customers: supports · Core utilities and types are used by feature modules.
- Core → Invoices: supports · Core utilities and types are used by feature modules.
- Core → Reports: supports · Core utilities and types are used by feature modules.
