# ShasPOS Pro — Phase 1 Architecture

## Frozen product boundary
- Existing ShasPOS Android app remains unchanged.
- New SaaS product: **ShasPOS Pro**.
- Flutter Android package: `com.shastech.shaspospro`.
- Online-only transactional operation.
- Flutter targets Android and Web first; Windows/desktop is supported by the same codebase.
- Retail edition first. Restaurant Edition is a later edition/module.
- Backend: PHP 8.x REST API + MySQL/MariaDB.
- Deployment: shared-hosting/cPanel safe.
- Subscription payment: ShasPay first, generic gateway adapter from day one.

## Runtime topology
```text
Flutter Android / Web / Windows
            |
          HTTPS
            |
       PHP REST API
            |
      MySQL/MariaDB
            |
       cPanel Cron
            |
     DB Job Queue

SaaS Super Admin (PHP + Bootstrap 5)
Subscription Engine -> PaymentGatewayInterface -> ShasPay / future gateways
```

## Non-negotiable rules
1. The server is authoritative for all transactional data.
2. No offline sales/purchases/stock/payment posting exists in Pro.
3. Every tenant-sensitive query is scoped before data access.
4. Flutter never decides authorization, stock truth, subscription entitlement or final financial totals.
5. Posted sales, returns, purchases, stock, FIFO, cash and ledgers are atomic DB transactions.
6. High-risk mutation endpoints use idempotency keys.
7. Gateway secrets exist only on the server.
8. All canonical timestamps are UTC.
9. Money uses decimal arithmetic; quantities support fractional units.
10. Multi-business and multi-outlet are first-class from the initial schema.

## Tenancy
```text
User
  -> business_users membership
     -> roles / permission overrides
     -> outlet access

Business
  -> Outlets
     -> Inventory Locations
     -> Registers
     -> Operational Documents
```

A user may belong to multiple businesses. An employee can be restricted to specific outlets. Operational rows carry `business_id`; outlet/location ownership is checked server-side.

## IDs
- Internal relational key: `BIGINT UNSIGNED AUTO_INCREMENT`.
- Public/API key: ULID stored as `CHAR(26)`.
- Human document numbers are separate and generated through a locked sequence service.
- Numeric IDs are never used as Flutter route/resource IDs.

## Online-only UX
Network state: `ONLINE`, `RECONNECTING`, `OFFLINE`. When offline, the app may preserve a current cart/form locally for UX, but mutation controls that would create authoritative business records are unavailable until connectivity returns.

## Shared-hosting compatibility
No Redis, RabbitMQ, WebSocket daemon, Supervisor, Node server, Docker or Kubernetes is required for launch. Background work uses the `job_queue` table plus cPanel cron.