PosApp - Modern Point-of-Sale System

A cross-platform Point-of-Sale (POS) application built with .NET MAUI and Blazor Hybrid for iPad, Android, and Windows. Designed with Clean Architecture principles, featuring offline-first capabilities, real-time inventory management, and comprehensive reporting.

🎯 Overview

PosApp is an enterprise-grade POS solution optimized for restaurants and retail businesses. The application works seamlessly offline and synchronizes data when connectivity is restored, ensuring uninterrupted service even in low-connectivity environments.

Key Highlights

• Cross-Platform: iPad (primary), Android, Windows support via .NET MAUI
• Offline-First: Full offline capabilities with automatic sync
• Cost Tracking: Price monitoring, profit margin analysis, and inventory costing
• Queue Management: Dual numbering system (order IDs + customer-facing queue numbers)
• Mobile Printing: Integrated receipt and label printing
• Sales Analytics: Daily, monthly, and product-level reporting
• Clean Architecture: Layered design for maintainability and testability

🛠️ Technology Stack

Layer	Technologies
UI	.NET MAUI + Blazor Hybrid (C# with WebView)
Business Logic	.NET 10, C# 14
Database	SQLite (offline)
Architecture	Clean Architecture (Domain-Driven Design)
Async	Task-based async/await throughout
Testing	xUnit, Moq

Target Frameworks: net10.0-ios, net10.0-android, net10.0-maccatalyst, net10.0-windows

📁 Project Structure

PosApp/
├── src/
│   ├── PosApp.Domain/                    # Core business entities & rules (no dependencies)
│   │   ├── Entities/                     # Order, Product, Payment, AppSettings
│   │   └── Enums/                        # OrderStatus, PaymentMethod, SyncStatus, QueueResetPeriod
│   │
│   ├── PosApp.Application/               # Use-cases & orchestration
│   │   ├── Services/                     # IOrderService, ICheckoutService, IProductService, etc.
│   │   ├── Repositories/                 # Interface definitions (implementation in Infrastructure)
│   │   └── Models/                       # DTOs & reports (CategorySalesReport, DailySaleSummary)
│   │
│   ├── PosApp.Infrastructure/            # Implementations (SQLite, HTTP, sync engine)
│   │   ├── Data/
│   │   │   ├── PosAppDbContext.cs        # EF Core context
│   │   │   └── Configurations/           # Entity configurations
│   │   ├── Repositories/                 # Concrete repository implementations
│   │   ├── Services/                     # Service implementations (checkout, orders, sync)
│   │   └── Utilities/                    # Helpers, formatters, extensions
│   │
│   └── PosApp.MauiBlazor/                # UI Layer (MAUI host + Blazor components)
│       ├── Components/                   # Blazor components (ProductGrid, CartPanel, etc.)
│       ├── Pages/                        # Blazor pages (Sales, Orders, Settings)
│       ├── Services/                     # Device-specific services
│       ├── Platforms/                    # Platform-specific code (iOS, Android, Windows)
│       └── Resources/                    # Styles, fonts, images
│
├── tests/
│   └── PosApp.Tests/                     # Unit tests (Domain, Application logic)
│       ├── Domain/                       # Entity and invariant tests
│       └── Application/                  # Use-case and service tests
│
└── docs/                                 # Feature documentation
    ├── QUEUE_NUMBER_SYSTEM.md           # Dual numbering system for orders
    ├── PRODUCT_CRUD_IMPLEMENTATION.md   # Product management workflows
    └── MOBILE_PRINTING.md                # Receipt & label printing

Dependency Rules

• Domain → No dependencies (pure business logic)
• Application → Only Domain + abstractions
• Infrastructure → Implements Application interfaces
• UI (MauiBlazor) → Depends on Application & Infrastructure via DI

✨ Core Features

1. Sales Management

• Product selection with real-time pricing
• Shopping cart with quantity management
• Multiple payment methods (Cash, Card, etc.)
• Order status tracking (Pending, Completed, Cancelled)

2. Queue Number System

Dual numbering for orders:

• OrderNumber: Technical ID (e.g., ORD-20260223143225) for sync and system integrity
• QueueNumber: Customer-facing sequential numbers (e.g., 12) with configurable reset periods
  • Daily reset (default)
  • Weekly reset (Monday)
  • Monthly reset
  • Never (continuous)

📖 See docs/QUEUE_NUMBER_SYSTEM.md for detailed implementation.

3. Offline-First Architecture

• All transactions saved locally first (SQLite)
• Automatic background sync when online
• Conflict resolution strategy
• Sync state tracking (PendingUpload, Synced, Failed, Conflict)

4. Inventory & Costing

• Product cost tracking and profit margin calculation
• Real-time inventory updates
• Category-based organization

5. Sales Analytics

• Daily sales summary (total, transaction count, average order value)
• Monthly sales reports
• Product-level sales analysis
• Category-wise breakdown

📖 See docs/PRODUCT_CRUD_IMPLEMENTATION.md for product workflows.

6. Mobile Printing

• Receipt printing with order details
• Label/ticket printing for kitchen displays
• Device-specific printer integration

📖 See docs/MOBILE_PRINTING.md for configuration.

7. Settings Management

• Configurable queue reset period
• Currency & locale formatting
• App-level configuration persistence

🚀 Getting Started

Prerequisites

• .NET SDK 10.0 or later
• Visual Studio 2022 (v17.10+) or VS Code with C# Dev Kit
• Platform SDKs for target platforms:
  • iOS: Xcode (Mac only)
  • Android: Android SDK
  • Windows: Windows SDK

Building the Project

# Build all projects
dotnet build PosApp.slnx

# Build specific platform
dotnet build -f net10.0-android
dotnet build -f net10.0-ios
dotnet build -f net10.0-windows10.0.19041.0

Running Tests

# Run all tests
dotnet test PosApp.slnx

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

Running the Application

# Android
dotnet run -f net10.0-android

# iOS (Mac only)
dotnet run -f net10.0-ios

# Windows
dotnet run -f net10.0-windows10.0.19041.0

🏗️ Architecture Principles

Clean Architecture

• Independence: Business logic independent of frameworks and UI
• Testability: Core logic testable without external dependencies
• Flexibility: Easy to swap implementations (e.g., different databases, APIs)

Offline-First

1. Always local first: All writes go to SQLite immediately
2. Async sync: Background sync when online
3. Conflict resolution: Server data takes precedence for master data; local orders preserved unless rejected
4. Device identification: DeviceId tracking for multi-device scenarios

Domain-Driven Design

• Entities: Order, Product, Payment with business invariants
• Value Objects: Enums (OrderStatus, PaymentMethod, SyncStatus)
• Repositories: Abstract data access behind interfaces
• Services: Coordinate complex workflows

👨‍💻 Development Guidelines

Code Organization

• Keep Domain classes pure (no infrastructure concerns)
• Use async/await throughout (Task-based)
• Constructor injection for all dependencies
• Nullable reference types enabled

Naming Conventions

• Interfaces: IOrderRepository, ICheckoutService
• Async methods: GetOrderAsync(), SaveOrderAsync()
• DTOs: OrderDto, SalesReportModel

Validation & Error Handling

• Domain entities enforce invariants in constructors
• Application layer returns Result<T> for operations that can fail
• Structured logging via ILogger<T>
• No exception throwing for normal business validation

Testing Strategy

• Unit test Domain invariants
• Mock repositories in Application tests
• Minimal UI tests (focus on logic)

See PosApp.Tests for test examples.

📚 Documentation

Document	Purpose
QUEUE_NUMBER_SYSTEM.md	Queue numbering architecture & implementation
PRODUCT_CRUD_IMPLEMENTATION.md	Product management workflows
MOBILE_PRINTING.md	Printing service configuration

🔄 Sync Engine

The application uses an offline-first sync strategy:

1. Upload Phase: Send local PendingUpload changes to server
2. Download Phase: Fetch remote updates (Products, Prices, Settings)
3. Conflict Resolution: Merge strategy based on entity type
   • Master data (Products): Server wins
   • Transactions (Orders): Local wins unless server rejects

Sync state tracked per record:

• PendingUpload - Not yet synced
• Synced - Successfully synced
• Failed - Sync failed (retry needed)
• Conflict - Conflicting changes detected

🎨 UI/Blazor Components

The application uses Blazor Hybrid with a modern component library for responsive, touch-friendly interfaces:

• ProductGrid: Browse and select items
• CartPanel: View and modify shopping cart
• CheckoutDialog: Payment processing
• OrderList: View order history
• ReportsPage: Analytics and sales data
• SettingsPage: Configuration management

Components are thin; business logic lives in Application services.

📊 Data Model

Core Entities

• Order: Customer transactions with status and queue numbers
• OrderItem: Line items within orders
• Product: Inventory items with pricing and cost
• Payment: Payment records with method tracking
• AppSettings: Configuration storage

All entities include:

• SyncStatus for offline-first support
• UpdatedAt timestamp (UTC) for sync reconciliation
• DeviceId for multi-device tracking
• ServerId for server reference (when synced)

🔒 Security Considerations

• No secrets stored in repository (use configuration)
• Async data access prevents blocking
• Input validation in Application layer
• Structured logging (no sensitive data in logs)

🤝 Contributing

When implementing features, follow:

1. Place code in correct layer (Domain/Application/Infrastructure/UI)
2. Use constructor injection (no service locators)
3. Maintain async APIs (no blocking calls)
4. Write unit tests for Domain/Application logic
5. Document public APIs with XML comments

📋 Project Status

✅ Completed

• Core POS functionality (Sales, Orders, Payments)
• Queue number system with configurable reset periods
• Offline-first architecture with SQLite
• Sales analytics and reporting

🚧 In Progress

• Mobile printing integration
• Advanced reporting features
• Multi-location support

📋 Planned

• Real-time sync with backend API
• Customer loyalty programs
• Inventory forecasting
• Multi-currency support

📝 License

[Add your license here]

---

Happy coding! 🚀 For questions or issues, refer to the documentation in docs/ folder or create an issue.