ExtroPOS Recovery Project — Modernization Baseline

This repository represents the authoritative modernization recovery of the original ExtroPOS commercial POS platform.

The original GitHub repository is no longer accessible. This repository preserves:

• Historical Features: 35 Screens, 67 Services, 26 Models, Database v31 schema evolutions.
• Business Rules: Complete catalog of registered pricing, SST, sales, table, printing, e-invoice, and stock rules.
• UI Workflows: Protected cashier muscle memory, touch ergonomics ($\ge 48\text{dp}$), and two-pane retail/F&B layouts.
• Architecture Decisions: Locked ADR-001 (6-Layer Clean Architecture & Legacy Bridge) and ADR-002 (PricingEngine & Integer Cents).
• Migration Strategy: Strangler Fig pattern for controlled evolution without rewriting from zero.

Version: 1.0.51+51
Architecture Standard: 6-Layer Clean Architecture & Legacy Compatibility Bridge
Governance: L.I.S.A. (Logical Intelligence & Software Assistant) + ADR Protocol

---

🏛️ Project Overview

ExtroPOS is an enterprise-capable, offline-first Point-of-Sale (POS) application built with Flutter targeting Android POS tablets (iMin, Sunmi, generic Android tablets) and Desktop environments (Linux/Windows/macOS).

This repository serves as the authoritative source of truth, containing:

1. Field-Tested Production System: 35 Screens, 67 Services, 26 Models, Database v31 schema evolutions, and hardware driver integrations.
2. Archaeology Knowledge Base (docs/Knowledge/): Complete audit of historical roadmaps, 10-part business rule catalogs, risk registers, and ergonomic layout specs.
3. Clean Architecture Framework: 6-layer architecture skeleton (core/, domain/, data/, features/, skins/, legacy/), locked ADRs (ADR-001, ADR-002), and Golden Master parity test protocols.

---

🔄 Modernization Strategy: The Strangler Fig Pattern

ExtroPOS is modernizing using a Strangler Migration Pattern:

Modernization by extraction, parity verification, and controlled migration — preserving production logic, customer workflows, and cashier muscle memory.

┌────────────────────────────────────────────────────────┐
│            skins/classic/ (Protected UI)               │
├────────────────────────────────────────────────────────┤
│           features/ (Application Use Cases)            │
├────────────────────────────────────────────────────────┤
│      domain/engines/ (PricingEngine - Integer Cents)   │
├────────────────────────────────────────────────────────┤
│      legacy/adapters/ (Legacy Compatibility Bridge)    │
├────────────────────────────────────────────────────────┤
│    data/ (DAOs, Hardware Event Queue, E-Invoice APIs)  │
└────────────────────────────────────────────────────────┘

---

📚 Repository Engineering Knowledge Base

All architectural contracts, risks, and business rules are maintained under docs/Knowledge/:

Document	Description
INDEX.md	Sitemap & Governance Guidelines.
CURRENT_STATE.md	Codebase Health, File Taxonomy, & Analyzer Diagnostic Baseline.
architecture_audit.md	FlashPOS Comparison Matrix & God Class Audits (DatabaseHelper, SalesService).
dependency_map.md	Hardware Drivers (Sunmi/USB/Bluetooth), Storage, & Dependency Topology.
risk_register.md	Risk Log & Mandatory Control Gates for Transactions, Money, and Hardware.
migration_strategy.md	Phased 7-Step Recovery & Domain Extraction Roadmap.
UI_PRESERVATION_CONTRACT.md	Cashier Muscle Memory Protection & Reference Oracle Parity Rules.
UI/ui_decision_notes.md	Ergonomics, Touch Specifications ($\ge 48\text{dp}$), & Retail/F&B Layout Specs.
HISTORICAL_ROADMAP_AND_FEATURES.md	Completed Phases 1-4, Database v1-v31 Schema Evolutions, & Feature Archive.
BUSINESS_RULE_CATALOG.md	Complete Catalog of Registered Rules (PRICE, SALE, TABLE, PRINT, STOCK).
ADR-001-architecture-boundary.md	[LOCKED] 6-Layer Clean Architecture & Legacy Bridge Standard.
ADR-002-pricing-authority.md	[LOCKED] Pure PricingEngine Domain Authority & Money Integer Cents.
MIGRATION_MAP.md	Clean Architecture Directory Skeleton & Legacy Migration Destinations.

---

⚡ Core Operational Features

• Dual Operating Modes: Retail Quick-Serve (Barcode Scanner, Fast Cart) & F&B Table Service (Floor Plan Grid, Status Colors, Table Merge/Move).
• Hardware Printing Engine: Native Android USB OTG serial, Sunmi inner printer SDK, Bluetooth ESC/POS, and kitchen order routing.
• Malaysian Compliance & Tax: LHDN E-Invoice HTTP submission with 2-minute background poller, 6% SST (Exclusive/Inclusive), and Malaysian 5-cent rounding rules.
• Advanced Inventory & Alerts: Real-time stock tracking, multi-level alert escalations (Info $\rightarrow$ Warning $\rightarrow$ Critical), and Supplier A-F Performance Matrix.
• Performance & Diagnostics: Paged sales query with LRU memory caching (TTL 5m), snapshot cold-start persistence, and receipt size anomaly monitoring.

---

🚀 How to Run & Build

1. Fetch Dependencies:

   flutter pub get

2. Run Application:

   flutter run

3. Execute Test Suite:

   flutter test