• English

    • Salon POS — Quickstart

    A full-featured point-of-sale system for salon, spa, and nail businesses, built with Flutter for Android tablets (1280×800 landscape). Runs entirely on the local network with an offline-first design and optional cloud sync.

    Architecture at a glance

    All devices → Shelf API (:8080) → Drift DB (Primary only) → CloudSyncWorker → PostgreSQL (AWS RDS)

    Every device — including the Primary itself — talks to a single local HTTPS API. Only the Primary owns the SQLite database. Switching between Primary and Secondary is a base-URL change; there is no branching logic in client code.

    RoleResponsibility
    PrimaryRuns the Shelf HTTPS server (:8080), owns the Drift database (67 tables), background-syncs to the cloud
    SecondaryNo local database; all operations go through the Primary's API
    EmergencyBufferWhen the Primary is unreachable, buffers operations locally and replays on reconnect

    See Architecture for the full LAN topology, security model, and handler system.

    Tech stack

    PurposePackage
    Local DB (Primary only)drift + sqlite3_flutter_libs
    Local API server (Primary only)shelf + shelf_router
    State managementflutter_riverpod + riverpod_annotation
    Routinggo_router
    HTTP clientdio
    Background serviceflutter_foreground_task
    Encryption / identitycryptography (Ed25519), crypto, basic_utils (TLS)
    Cloud DBPostgreSQL on AWS RDS (via cloud ingestion API)

    Getting started

    flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter analyze
flutter test
flutter run

    The app targets Android tablets in landscape. Config files live in config/ — copy config/dev.example.json to config/dev.json and set your dev machine's LAN IP.

    Build (release APKs)

    # Linux/macOS
bash scripts/build_apk.sh

# Windows
powershell scripts/build_apk.ps1

    Environment URLs are injected via --dart-define-from-file (config/dev.json, config/uat.json, config/prod.json).

    Project layout

    lib/
├── main.dart              # Bootstrap, DI container, singleton wiring
├── app.dart               # MaterialApp.router, MainScaffold, NavigationRail
├── core/
│   ├── database/          # Drift schema (67 tables, v66) + demo seed
│   ├── network/           # Shelf API server + Dio client + 28 handlers + LAN auth
│   ├── sync/              # Cloud outbox sync, EmergencyBuffer, restore, roster
│   ├── router/            # GoRouter (~35 routes, auth guard)
│   ├── theme/             # Light/dark themes, accent palettes, spacing
│   ├── device/            # Ed25519 identity, device role state machine
│   ├── observability/     # Structured logging, metrics, error upload, ring buffer
│   ├── push/              # Firebase Cloud Messaging (Primary only)
│   ├── data/              # Domain-aware cache invalidation
│   ├── notifications/     # Staff alert bell (Drift-based)
│   └── utils/             # 23 stateless helpers (money, dates, commissions, etc.)
├── features/              # 14 feature modules (see Features below)
│   ├── check_in/          # Dashboard: queue, service grid, cart, launch checkout
│   ├── checkout/          # Payment collection, CodePay terminal, receipts
│   ├── ticket/            # Order management: void, refund, exchange, audit
│   ├── appointment/       # Calendar, scheduling, online booking requests
│   ├── customers/         # CRM: profiles, membership tiers, store credit
│   ├── settings/          # Administration: staff, services, products, config
│   ├── session/           # Shift open/close, cash reconciliation, Z-report
│   ├── staff/             # Clock in/out, PIN auth, permissions, idle detection
│   ├── reporting/         # 15+ report sections, PDF/CSV export
│   ├── resources/         # Room/chair/equipment management
│   ├── waitlist/          # Walk-in queue management
│   ├── card_transactions/ # Terminal card payment history
│   ├── notifications/     # In-app notification bell UI
│   └── onboarding/        # First-run guided setup wizard
└── shared/
    ├── models/            # TicketWithDetails, CheckoutModels, CustomerUiModel, etc.
    └── widgets/           # AmountNumpad, AppToast, GlassPanel, AddCustomerDialog, etc.

    Key documentation pages

    • Architecture — LAN topology, Primary/Secondary device roles, Shelf handlers, TLS & Ed25519 security, offline-first design
    • Features — All 14 feature modules with purpose, key files, cross-feature dependencies
    • Data Models — 67-table Drift schema, sync outbox/registry, shared domain models
    • Operations — Build config, cloud sync pipeline, observability, backup/restore, deployment
    • Testing — Test structure, pump harness, mock Dio, coverage patterns

    Feature highlights

    • Check-in & waiting list — customer search, walk-ins, service selection, per-service staff assignment, VIP/allergy/blacklist alerts, visit history
    • Tickets & checkout — service and retail-product sales, discounts, tax, surcharge, tips, printed/PDF receipts
    • Appointments — calendar with resource and staff scheduling, recurring appointments, online booking request management
    • Staff & RBAC — PIN login, role-based permissions with a permission matrix, per-action privilege escalation
    • Commission & payroll — percentage or fixed-amount commission, hourly wages, labor-cost and staff-earnings reports
    • Gift cards & loyalty — sale, redemption, balance tracking, loyalty points
    • Card payments — CodePay terminal integration for sale, void, refund, tip adjustment, and batch settlement
    • Reporting — Z-report close-out plus sales, attendance, labor-cost, appointment, resource, customer, gift-card, and loyalty analytics
    • Cloud — account onboarding, multi-store registration, push-sync upload, and pull-sync restore
    • Multi-device security — per-device Ed25519 identities, fingerprint-pinned HTTPS on the LAN, zero-trust session tokens