How pixelweavedev/step_up_fuels works
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: injection_container.dart DI container · invoices Invoices · dashboard Dashboard · customers Customers
Components 22
App Shell
Flutter entrypoint, root widget, routing, and dependency wiring.
- main · Bootstraps the application.
lib/main.dart - App · Top-level app widget and theme composition.
lib/app/app.dart - DI container · Assembles repositories, services, and use cases.
lib/app/di/injection_container.dart - Router · Defines routes and route names for the app.
lib/app/router/app_router.dart - App DB · 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.
Feature Modules
Business domains implemented with presentation, application, domain, and data layers.
- Dashboard · Summarizes data across modules for the home view and reporting entry points.
lib/features/dashboard - Customers · Customer profiles, contacts, sites, credit limits, and customer lifecycle.
lib/features/customers - Invoices · Invoice creation, posting, cancellation, invoice items, and GST calculation.
lib/features/invoices - Purchases · Fuel purchases, suppliers, purchase status, and related entry flows.
lib/features/purchases - Inventory · Stock levels, movements, storage locations, adjustments, and reconciliation.
lib/features/inventory - Vehicles · Vehicle records, service records, and assignment tracking.
lib/features/vehicles - Drivers · Driver records and driver assignment workflows.
lib/features/drivers - Payments · Payment records used by billing and purchase workflows.
lib/features/payments - Ledger · Ledger accounts and entries used for accounting-style reporting and integration.
lib/features/ledger - Reports · Reporting service plus Excel and PDF exporters.
lib/features/reports - Settings · Company profile, invoice settings, print settings, documents, and users tables.
lib/features/settings
Platform Shells
Native platform wrappers around the shared Flutter runtime.
Connections 32
- 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.