#Features

Salon POS has 14 feature modules, each following a data/ (providers, repositories, DTOs, calc logic) and presentation/ (screens, widgets) organization. Riverpod is the primary dependency injection mechanism.

#Feature dependency map

check_in ──depends on──▶ appointment, checkout, ticket, customers,
                          session, settings, staff, resources, reporting, waitlist

ticket ──depends on──▶ checkout, customers, settings, staff, resources, card_transactions

appointment ──depends on──▶ check_in, settings, staff, resources, customers, waitlist

checkout ──depends on──▶ customers, settings, staff

reporting ──depends on──▶ (mostly self-contained, uses shared widgets)

settings  ◀──depended on by── 10+ features (master-data layer)

settings is the most depended-upon module. check_in is the most dependent module (imports from 10+ other features).

#check_in — Dashboard & Service Queue

Purpose: The core operational hub where staff serve waiting customers, build service/product carts, and launch checkout.

Key screens:

• Dashboard — left/right panels: queue band (waiting customers), service catalogue grid, cart panel, staff/resource status
• Check-in screen — customer search, walk-in registration, service selection, visit history, per-service staff assignment

Key data files: lib/features/check_in/data/ — providers, repositories for tickets, cart state, staff/resource status, risk checks, quick-checkout flow

Cross-feature imports: appointment (booking request badges), checkout (launch), ticket (staleness, redirect), customers (search, badges), session (staff assignment), settings (services, products, staff), staff (assignment), resources (status), waitlist

#checkout — Payment Collection

Purpose: Collect payments for tickets — splits, discounts, gift cards, loyalty, credit card terminal (CodePay), receipt printing.

Key screens:

• Checkout dialog with payment flow widgets
• CodePay terminal sale overlay (ECR Hub codec, LAN/intent terminals)

Key data files: lib/features/checkout/data/ — checkout calculation, repository, receipt service/printer, discount/gift-card/loyalty/coupon calculators, CodePay ECR Hub integration (sale, reversal, batch-close, tip-adjust flows)

Notable: The CodePay integration is a critical external dependency — card payments require a physical terminal communicating over LAN or Android intents.

#ticket — Order Management

Purpose: Browse, filter, void, refund, exchange tickets (orders). Supports staff reassignment and full audit trail.

Key screens:

• Ticket list with filter bar (date, staff, status)
• Ticket cards with live detail panel
• Void/refund/exchange/reassign flows

Key data files: lib/features/ticket/data/ — ticket provider/repository, refund/exchange calculators, filter keys

Cross-feature imports: checkout (payments/refunds), customers, settings, staff, resources, card_transactions

#appointment — Calendar & Scheduling

Purpose: Calendar views (month/week/day), create/edit/recurring appointments, manage online booking requests.

Key screens:

• Month/week/day calendar views with block cards
• Appointment detail/new sheets
• Booking requests sheet for online bookings
• Hatch painter for time-block visualization

Key data files: lib/features/appointment/data/ — providers/repos for appointments + booking requests, block layout, recurrence, customer risk, staff-on-shift filter, service-hours filter

#customers — CRM

Purpose: Customer profiles, membership tiers, store credit, package/value-card management.

Key screens:

• Customer list with detail panel
• Edit dialog
• Membership tier cards/management
• Store credit dialog
• Package admin actions (redeem, transfer)

Key data files: lib/features/customers/data/ — membership provider/repo, package repository, eligibility checks

#settings — Administration (Largest Module)

Purpose: Everything configurable about the business — the de-facto master-data layer used by 10+ other features.

Key screens (30+):

• Staff hub — create/edit staff, permissions, schedules
• Service/product/package forms
• Category items
• Gift cards management
• Loyalty configuration
• Permission matrix
• Printer settings
• Terminal (CodePay) settings
• Device role management (Primary/Secondary promotion)
• Cloud sync status & manual sync
• Backup & restore
• Store info
• Schedule matrix
• Time-off types
• Language selection
• Cloud register/transfer flow
• Settings Kit: reusable widget library for settings forms

Key data files: lib/features/settings/data/ — the largest data layer with providers/repos for staff, services, products, categories, packages, gift cards, store info, settings, cloud config, booking links, cancel reasons, time-off types, device role, cloud register/transfer, schedule matrix, first backup

#session — Shift Management

Purpose: Open/close business sessions, cash reconciliation, Z-report generation.

Key screens:

• Session closeout screen
• Cash denomination counter
• Cash reconciliation
• Open-session dialog
• Session badge (shown in top bar)

Key data files: lib/features/session/data/ — session provider/repo, DTOs, closeout open-tickets check, cash variance calculator, cash-input parser

#staff — Staff Operations

Purpose: Clock in/out, PIN authentication, permission checks, idle detection.

Key screens:

• PIN screen (login)
• Time-clock entry/manage screens
• Clock badge (shown in top bar)
• PIN pad widget
• Privilege escalation dialog (for permission-gated actions)
• Idle warning overlay

Key data files: lib/features/staff/data/ — active clocks, assignment filters, permission/role repos, schedule repo, staff session, time-clock repo, service-staff filter, availability checks

#reporting — Business Intelligence

Purpose: Comprehensive reporting with ~15 sections, PDF export, CSV export.

Report sections:

• KPI band (revenue, ticket count, average)
• Revenue summary
• Staff earnings (commissions + hourly)
• Sales detail
• Payments breakdown
• Discounts summary
• Gift card activity
• Loyalty points activity
• Appointment statistics
• Attendance report
• Labor cost report
• Customer analytics
• Package liability
• Resource utilization
• Voided tickets
• Session history (Z-reports)

Key data files: lib/features/reporting/data/ — revenue calc, staff earnings calc, sales detail, discount/gift-card/loyalty calcs, labor cost, package liability, appointment stats, customer analytics, resource utilization, session Z-report, CSV export, refund/exchange adjustments

#resources — Resource Management

Purpose: Manage rooms, chairs, equipment. Conflict detection when double-booking.

Key screens:

• Resources list screen
• Resource picker section
• Type display

Key data files: lib/features/resources/data/ — resource provider/repo, conflict detection

#waitlist — Walk-in Queue

Purpose: Manage customers waiting without appointments. Match logic for service availability.

Key screens:

• Waitlist screen

Key data files: lib/features/waitlist/data/ — waitlist provider/repo, match logic

#card_transactions — Card Payment History

Purpose: Browse terminal card transactions, tip adjustments.

Key screens:

• Card transactions list
• Detail sheet
• Transaction tile

Key data files: lib/features/card_transactions/data/ — card transaction DTO, provider, repository

#notifications — Real-time Alerts

Purpose: In-app notification bell with sound for booking requests, session events.

Key screens:

• Notification bell (top bar)
• Toast host
• Display screen

Key data files: lib/features/notifications/data/ — notification provider/repo, refresh signal, sound service

#onboarding — First-run Setup

Purpose: Guided setup wizard for new stores (welcome, store info, owner account, service flow, menu intro, connect secondary, sign-in email/OTP/store-picker).

Key screens:

• Onboarding screen shell
• Sign-in panel
• Step-by-step wizard
• Registration flow (cloud account creation)

Key data files: lib/features/onboarding/data/ — admin repo, cloud secondary enroll, cloud sign-in, cloud store registrar, onboarding controller/redirect/state, sign-in controller, store hours defaults

#Shared modules

#lib/shared/models/

#lib/shared/widgets/

#Patterns across features

• Repository pattern: Every feature has XxxRepository classes that take a Dio instance. Screen widgets use XxxProvider (Riverpod) which wraps the repository.
• Feature-based folder structure: lib/features/<name>/data/ for business logic, lib/features/<name>/presentation/ for UI.
• Cross-feature imports: Features import other features' providers, not their repositories or widgets directly.
• settings as master-data: Most features depend on settings for staff, service, product, category, and store-info providers.