# ShasPOS Pro — Flutter Client Structure

Android application ID: `com.shastech.shaspospro`

Initial targets: Android + Web; Windows desktop follows from the same project architecture. The client is online-only: there is no local business database and no offline transaction queue.

```text
shaspos_pro/
├── lib/
│   ├── app/
│   │   ├── app.dart
│   │   ├── router.dart
│   │   └── bootstrap.dart
│   ├── core/
│   │   ├── api/
│   │   │   ├── api_client.dart
│   │   │   ├── api_response.dart
│   │   │   └── api_error.dart
│   │   ├── auth/
│   │   ├── config/
│   │   ├── connectivity/
│   │   ├── errors/
│   │   ├── localization/
│   │   ├── security/
│   │   ├── storage/
│   │   ├── theme/
│   │   └── utils/
│   ├── features/
│   │   ├── auth/
│   │   ├── onboarding/
│   │   ├── dashboard/
│   │   ├── pos/
│   │   ├── sales/
│   │   ├── returns/
│   │   ├── products/
│   │   ├── categories/
│   │   ├── inventory/
│   │   ├── stock_take/
│   │   ├── batches/
│   │   ├── customers/
│   │   ├── customer_credit/
│   │   ├── suppliers/
│   │   ├── purchases/
│   │   ├── purchase_orders/
│   │   ├── cash_register/
│   │   ├── accounting/
│   │   ├── reports/
│   │   ├── staff/
│   │   ├── roles/
│   │   ├── outlets/
│   │   ├── devices/
│   │   ├── subscription/
│   │   └── settings/
│   └── shared/
│       ├── widgets/
│       ├── models/
│       └── layouts/
├── android/
├── web/
├── windows/
├── linux/
├── macos/
└── test/
```

## Feature convention

Each substantial feature should use:

```text
feature/
├── data/
│   ├── datasources/
│   ├── dto/
│   └── repositories/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── usecases/
└── presentation/
    ├── controllers/
    ├── pages/
    └── widgets/
```

Do not over-abstract tiny screens; use the boundary when a feature has real domain behavior.

## Responsive layout contract

- Compact: phone — single-pane navigation, POS cart as dedicated/overlay screen.
- Medium: tablet — adaptive two-pane where useful.
- Expanded: desktop/web — navigation rail/sidebar and POS product grid + persistent cart.
- Business logic and API repositories remain shared across layouts.

## Connectivity contract

States: `online`, `reconnecting`, `offline`.

When offline, the app may preserve current UI/cart state in memory, but it must not commit a sale, payment, return, stock change, purchase, or financial posting. No background offline mutation queue is permitted in this edition.

## Authentication storage

- Android/desktop: secure OS-backed credential storage for refresh token.
- Web: prefer secure server-issued cookie/session strategy where supported by final API deployment; never place gateway secrets in Flutter.
- Access token is short-lived and never considered authorization by itself; server middleware revalidates tenant, outlet, permission and subscription.