BMS is a local-first business management system for retail and wholesale operations, built with Flutter. All data is stored on-device using SQLite.

---

Features

Sales

• POS - touch-optimised point-of-sale with barcode scan, line-item discounts, and bill-level discounts
• Quick Sales - no-invoice cash sales for fast counter transactions, tracked separately from invoiced sales
• Invoices - full invoice lifecycle (open, partial, paid, void) with PDF export and share

Stock

• Inventory - product catalogue with units, categories, reorder levels, and real-time stock levels
• GRN - goods receipt workflow that stocks in products, updates cost price, and posts to supplier ledger

Finance

• Customers and Debtors - credit sales, outstanding balances, payment collection, debtor ageing
• Suppliers - supplier ledger, purchase history, payment tracking
• Cheques - post-dated cheque register with due-date reminders
• Petty Cash - daily petty cash entries with receipt photos and approval workflow

Admin

• Dashboard - real-time sales summary, top products, and stock valuation
• Reports - sales, stock, and debtor reports
• Users - role-based access control with three tiers
• Audit log - immutable, insert-only financial audit trail

---

Tech Stack

Layer	Technology
UI	Flutter 3.44 + Material 3
State	Riverpod 3.x with riverpod_annotation
Navigation	go_router 14.x
Database	Drift 2.34 on SQLite (WAL mode, FK enforced)
Models	Freezed 3.x
Auth	bcrypt (logRounds 12) + flutter_secure_storage
Primary keys	UUID v7 (time-ordered, collision-safe)
PDF	pdf + printing packages
Charts	fl_chart

---

Project Structure

lib/
  core/
    router/       # go_router setup, route guards, route constants
    theme/        # AppTheme, AppColors, AppTextStyles
    utils/        # Currency, date, and general utilities
  data/
    database/
      daos/       # Drift DAOs - one per domain (inventory, sales, suppliers...)
      tables/     # Drift table definitions
      app_database.dart
    models/       # Freezed value objects (UserModel etc.)
  features/       # Feature-first screens
    auth/
    dashboard/
    inventory/
    invoices/
    pos/
    quick_sales/
    grn/
    customers/
    suppliers/
    cheques/
    petty_cash/
    reports/
    users/
    settings/
  providers/      # Riverpod providers per domain
  shared/
    widgets/      # Reusable widgets (sidebar, filter bar, error widget)

---

Getting Started

Prerequisites

• Flutter 3.24 or later
• Dart 3.8 or later

Install and run

git clone https://github.com/getbms/BMS.git
cd BMS
flutter pub get
dart run build_runner build
flutter run

The primary target is Windows desktop. For development on macOS, run on Chrome:

flutter run -d chrome --web-port 9090 --no-wasm

Default credentials

Field	Value
Username	dev
Password	changeme

Change the password immediately after first login via Settings.

---

Development

Code generation

Drift DAOs and Riverpod providers use build_runner:

dart run build_runner build
# watch mode during development
dart run build_runner watch --delete-conflicting-outputs

Database schema changes

1. Bump schemaVersion in AppDatabase
2. Add a migration step in onUpgrade
3. Never alter existing tables manually - always use migrations

Clearing the web database

The web build uses IndexedDB. After a schema change, clear the old database:

Chrome DevTools -> Application -> IndexedDB -> delete bms_local -> refresh

Adding a route permission

Edit RouteGuard._adminOnlyRoutes in lib/core/router/route_guard.dart.

Role permissions

Feature	Cashier	Admin	Developer
POS	yes	yes	yes
Inventory (view)	yes	yes	yes
Inventory (edit)	no	yes	yes
Invoices	no	yes	yes
Quick Sales	no	yes	yes
GRN	no	yes	yes
Customers	yes	yes	yes
Debtors	no	yes	yes
Suppliers	no	yes	yes
Cheques	no	yes	yes
Petty Cash	no	yes	yes
Reports	no	yes	yes
Users	no	no	yes
Settings	no	yes	yes

---

License

Apache License 2.0 - see LICENSE for details.