Promsell — POS Community Edition

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   🛒  PROMSELL  —  Offline-first Mobile POS for Merchants    ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Promsell — POS Community Edition

An offline-first mobile POS system built with Flutter for small businesses and local merchants.

5
📱 Tabs

2
🌐 Languages

3
🎨 Themes

100%
📴 Offline

SQLite
💾 Storage

Promsell POS Community Edition is an open-source point-of-sale application designed for small shops, market stalls, and local merchants who need a fast, reliable, and offline-capable cash register on their phone or tablet. Built with Flutter and Drift SQLite, it works without an internet connection, supports Thai and English with live language switching, and provides full sales tracking, inventory management, and reporting.

Latest Release: v0.8.0 — Full barcode scanning system (camera scan, manual entry, auto-generation, settings). AddProductPage 2-tab redesign. Image system UX fixes (shared bottom sheet, temp file cleanup, draft validation, error handling). 351 passing tests.

Features

Feature	Description
Sale	Searchable product catalog, category chips, adaptive cart command panel, stock-limit controls, cart quantity badges, multi-method checkout, quick cash chips, payment references, change calculation, per-item/cart discount with preset chips, multi-select bulk actions, swipe gestures, drag-to-reorder, resizable panel, compact/ultra-compact modes, direct quantity input tap dialog with stock clamping. v0.7.2: Single-row item redesign (3-zone layout), press-scale button animations with haptic, FAB bounce/pulse, removed cart search, compact cart theming matches normal cart. v0.7.1: Compact Cart Mode — floating icon with item-count badge opens bottom sheet. v0.6.2 UX: checkbox 48dp touch targets, drag tooltips, focus indicators, delete confirmations, keyboard submit on discount, toast tap-dismiss, drag performance refactor
Draft Cart	Auto-save every 1.5s; configurable max drafts (5–100); search + sort; count badge; auto-archive after 7 days; switch/rename/delete drafts; active draft restored on app launch; cleared on checkout
Discount	Per-item / per-cart discount (% or ฿) with live preview; merchant-configurable preset groups with quick-apply chips; max discount clamping; full payment sheet breakdown; VAT applied after discounts
Products	List/grid toggle, category filter chips with color/icon, image picker (gallery/camera) with pure Dart compression + thumbnail system, `CachedNetworkImage`, configurable image quality, `_StockBadge` (traffic-light), add/edit/delete with category, price, stock, `trackStock` toggle, active/inactive toggle, orphaned file cleanup, remove-then-cancel protection. Barcode — camera scan (EAN-13/8, UPC-A/E, Code 128/39, ITF), manual number entry fallback, auto-generate from timestamp, duplicate prevention (schema v16 unique index). Category Management — drag-drop reordering, color + icon picker (10 colors / 21 icons), product count badges, search, bulk delete. Schema v15
History	Date-ranged receipt-like sale history with expandable item breakdown, receipt numbers, VOIDED badge, VAT breakdown rows (Subtotal + VAT rate %) when VAT is active, void sale action with reason, notes, and search bar (filter by receipt number, payment method, or amount)
Report	Dashboard cards for net revenue (excludes voided), voided summary, payment method breakdown, top 5 products, date filter chip, pull-to-refresh, and empty states
Inventory	Inventory audit log (SALE, VOID_REVERSAL, ADJUSTMENT_IN/OUT), manual stock adjustment dialog with reason, and per-product log viewer
Settings	Elderly-friendly redesign with larger touch targets (48dp icons, 64dp tiles). Dashboard cards with gradient backgrounds and status badges on every page. Dialog-based visual pickers for language/theme with icon-based option cards. PromptPay ID validation (phone 10 digits / citizen ID 13 digits). Shop Info inline form with live preview and phone auto-format. Backup reminder switch + preset frequency picker (3/7/14/30 days). "Reset to Defaults" confirmation dialog. Root page dashboard with 5 summary badges and grouped sections (`Store & Business`, `Payments`, `System & Data`) with colored status chips on every tile. v0.7.2: 3-level hierarchy (Root → SubTopic → Page) with flattened search, backup encryption toggle, theme color tokens (`AppColors`) replacing hardcoded values. v0.7.1: Compact Cart Mode toggle, global theme unification (green accent `#00C853`, dark bg `#0D1117`, 16px card / 12px button radius), readability fixes for dark mode badges and icons
Void / Refund	Atomic void sale flow: marks VOIDED, restores stock, logs VOID_REVERSAL; receipt number generation
Receipt Preview	On-screen preview in `thermal` (80mm paper) and `card` styles, with independent pre/post-sale toggles and `"none"` option; pinch-to-zoom full-screen dialog
Receipt PDF	Print and share receipts as PDF with Thai font support; 80mm thermal + A4 layouts; PromptPay QR on receipt; centralized `ImageViewerDialog` for product/receipt images
PromptPay QR	EMVCo-compliant QR generation for static/dynamic payments; integrated into payment sheet; configurable PromptPay ID (phone or citizen ID)
Backup & Restore	Full SQLite export/import with WAL checkpoint and schema validation; CSV export for sales & products; configurable backup reminder banner
VAT	`NONE` / `INCLUSIVE` / `EXCLUSIVE` modes with correct subtotal/VAT/total breakdown on receipts and PDFs; VAT mode and rate are snapshotted at sale time and used for accurate historical reprints
Offline-first	All data stored locally in SQLite via Drift — no internet required
Material 3	Merchant Command Deck refresh with shared theme tokens and responsive UI primitives
i18n	Full localization via Flutter ARB files, easy to add more languages

Tech stack

Layer	Technology
Framework	Flutter 3.x · Dart 3.11+
State management	flutter_bloc (BLoC + Cubit pattern)
Database	Drift (SQLite ORM) with code generation — 9 tables, UUID PKs
DI	injectable + get_it (compile-time safe)
Routing	Navigator + lazy-loaded tabs
Persistence	SettingsLocalDatasource (Drift-backed typed key-value store); Drift tables for receipt sequences
Localization	flutter_localizations + Flutter ARB intl
PDF / Print	pdf + printing
Barcode / QR	mobile_scanner (product scan + checkout) + qr_flutter (PromptPay EMVCo)
Share / Export	share_plus + file_picker + csv
Image handling	image_picker + image (pure Dart compression) + cached_network_image (gallery/camera → local JPEG + thumbnails, configurable quality, orphaned cleanup)
Design	Material 3, NotoSansThai (bundled local fonts), shared UI primitives

Quick start

Prerequisites

Flutter SDK ≥ 3.11 (install guide)
Android Studio or Xcode for device/emulator
Git

Install and run

# 1. Clone
git clone https://github.com/teeprakorn1/promsell-pos-ce.git
cd promsell-pos-ce
 
# 2. Install dependencies
flutter pub get
 
# 3. Generate code (Drift, l10n)
flutter gen-l10n
dart run build_runner build --delete-conflicting-outputs
 
# 4. Run on connected device or emulator
flutter run

Build release APK

flutter build apk --release

The APK will be at build/app/outputs/flutter-apk/app-release.apk.

For more details, see docs/USAGE.md.

Project structure

promsell-pos-ce/
├── lib/
│   ├── core/
│   │   ├── database/          # Drift schema, tables, and migrations
│   │   ├── di/                # injectable + get_it DI
│   │   ├── extensions/        # context.l10n helper
│   │   ├── utils/             # IdGenerator, payment_method, etc.
│   │   └── widgets/           # shared UI primitives
│   ├── features/
│   │   ├── sale/              # Cart + checkout
│   │   ├── product/           # CRUD inventory
│   │   ├── receipt/           # PDF receipt, labels, PromptPay QR
│   │   ├── history/           # Sale history viewer + void dialog
│   │   ├── report/            # Analytics dashboard (net revenue)
│   │   ├── inventory/         # Inventory log viewer + stock adjust
│   │   └── settings/          # Theme, locale, shop info
│   ├── l10n/                  # ARB files (app_th.arb, app_en.arb)
│   └── main.dart              # App entry + 5-tab shell
├── docs/
│   ├── ARCHITECTURE.md        # Deep technical architecture (C4, data flow, ADRs)
│   ├── USAGE.md               # Detailed usage guide
│   ├── DEPLOY.md              # Build, signing, release checklist
│   ├── DATABASE.md            # Full database handbook (ERD, schema, migration)
│   └── architecture/          # PlantUML source files (.puml)
├── android/                   # Android platform code
├── ios/                       # iOS platform code
├── test/                      # Unit + widget tests
├── pubspec.yaml
├── l10n.yaml
├── CODEBASE.md                # Architecture, modules, file dependency map
├── CONTRIBUTING.md            # Contribution guide
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CHANGELOG.md
├── LICENSE
└── README.md

Each feature follows Clean Architecture:

features/<name>/
├── data/
│   ├── datasources/      # Drift DAO wrappers
│   └── repositories/     # Repository implementations
├── domain/
│   ├── entities/         # Pure Dart models
│   ├── repositories/     # Abstract interfaces
│   └── usecases/         # Business logic
└── presentation/
    ├── bloc/ or cubit/   # State management
    ├── pages/            # Page-level UI
    └── widgets/          # Extracted reusable widgets

Screenshots

Help wanted! We'd love real device screenshots here. To contribute: run the app in release mode, capture each tab, and open a PR adding images to docs/screenshots/. Suggested filenames: sale.png, products.png, history.png, report.png, settings.png.

Sale	Products	History	Report	Settings
TBA	TBA	TBA	TBA	TBA

Roadmap

Phase 1 (in progress)

Future

Receipt printing via Bluetooth thermal printer
PDF receipt export and share (v0.3.0)
Multi-shop support
Cloud backup and restore
R13 — Barcode System (v0.8.0): Camera barcode scanning (EAN/UPC/Code128/Code39/ITF), manual entry fallback, auto-generation with custom prefix, duplicate prevention (schema v16), BarcodeSettingsPage with scan/beep/prefix toggles + help section for non-technical staff. Image system UX fixes: shared showImageSourceSheet(), temp file lifecycle, draft path validation, error handling, remove confirmation, orphaned image cleanup
CSV export for products and sales (v0.6.0)
Customer management and loyalty
More languages (Lao, Khmer, Burmese, Vietnamese)

Testing

351 tests covering every application layer:

Layer	What's tested	Count
Domain	Entity equality, use case delegation, discount math, `InventoryLog` domain, `ReportCalculator` extension	~40
BLoC / Cubit	Event→state transitions, discount events, draft events, cart discount persistence, stock policy, `InventoryLogCubit`, `ReportCubit`	~35
Repository	Impl with mocked datasources	~20
Datasource	Real in-memory SQLite (Drift)	~12
Services	ReceiptNumberService, InventoryLogService, ReceiptPdfService	~15
Widget	Page tests + 16 extracted widget tests (`CartItemCard`, `OnboardingSection`, `PromptpayPreviewCard`, etc.)	~50
Integration	Checkout flow, sale integrity (void + adjust)	13
L10n parity	EN/TH key coverage, non-empty values, params	8

Running tests

# All tests
flutter test

# With coverage
flutter test --coverage

# Single file
flutter test test/integration/checkout_flow_test.dart

Test helpers

File	Purpose
`test/helpers/mocks.dart`	All mock classes (repos, datasources, use cases, BLoCs)
`test/helpers/pump_app.dart`	`pumpApp` extension with BlocProviders + l10n
`test/helpers/fake_database.dart`	In-memory Drift DB factory

Contributing

Contributions are welcome — bug reports, feature suggestions, or pull requests.

Read CONTRIBUTING.md for the full guide: branch naming, commit conventions, code style, and testing requirements.

For security vulnerabilities, see SECURITY.md — do not file public issues.

Documentation

Document	Contents
`CODEBASE.md`	Architecture diagram, module reference, file dependency map
`docs/ARCHITECTURE.md`	Deep technical: C4 diagrams, data flows, transaction boundaries, DI graph, ADRs
`docs/DATABASE.md`	Full database handbook: ERD, schema, indexes, migration, query patterns
`docs/USAGE.md`	Detailed usage guide: setup, build, settings, i18n, troubleshooting
`docs/DEPLOY.md`	Build, signing, release checklist, smoke test
`docs/PRIVACY_POLICY.md`	Privacy policy template for Play Store / App Store
`docs/STORE_SUBMISSION.md`	Store submission checklist: keystore, screenshots, build commands, console setup
`CHANGELOG.md`	Version history, breaking changes, migration notes

License

Licensed under the GNU Affero General Public License v3.0 — see LICENSE for details.

Copyright (C) 2026 MN Lizard Team

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Built by MN Lizard Team

Creator & Core Maintainer: @teeprakorn1

Contributors: @FrameHandsomez

_{Promsell POS Community Edition · v0.8.0 · AGPL-3.0}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Promsell — POS Community Edition

Table of contents

Features

Tech stack

Quick start

Prerequisites

Install and run

Build release APK

Project structure

Screenshots

Roadmap

Phase 1 (in progress)

Future

Testing

Running tests

Test helpers

Contributing

Documentation

License

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github		.github
android		android
assets		assets
docs		docs
fastlane/metadata		fastlane/metadata
ios		ios
lib		lib
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
.metadata		.metadata
CHANGELOG.md		CHANGELOG.md
CODEBASE.md		CODEBASE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
analysis_options.yaml		analysis_options.yaml
build.yaml		build.yaml
devtools_options.yaml		devtools_options.yaml
l10n.yaml		l10n.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml
scan_entities.js		scan_entities.js

Folders and files

Latest commit

History

Repository files navigation

Promsell — POS Community Edition

Table of contents

Features

Tech stack

Quick start

Prerequisites

Install and run

Build release APK

Project structure

Screenshots

Roadmap

Phase 1 (in progress)

Future

Testing

Running tests

Test helpers

Contributing

Documentation

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages