# Flow Charts (Mermaid)

These diagrams are intended to quickly explain the main flows in the Rewarder system.

## 1) System Context (Actors → System)

```mermaid
flowchart LR
  A[Admin/Manager] -->|Manage platform data| SYS[Rewarder System]
  S[Shopkeeper] -->|Manage catalog/offers/rewards| SYS
  C[Customer] -->|View offers / wallet / orders| SYS
  G[Guest] -->|Browse shops (landing page)| SYS

  SYS --> DB[(Database)]
```

## 2) Authentication Gate (High Level)

```mermaid
flowchart TD
  R[Incoming Request] --> F{Auth Filter}
  F -->|Route is / or /auth/*| P[Allow]
  F -->|Not logged in| L[Redirect to /auth/login]
  F -->|Logged in| P
  P --> C[Controller Action]
  C --> V[View Response]
```

## 3) Admin Flow (Subscriptions → Shops)

```mermaid
flowchart TD
  A[Admin/Manager] --> SP[Maintain Subscription Plans]
  A --> SH[Maintain Shops]
  SH --> AS[Assign Shopkeeper to Shop]
  SP --> SS[Assign Subscription to Shop]
  SS --> FV[Shop appears for browsing]
```

## 4) Shopkeeper Flow (Setup → Record Purchase)

```mermaid
flowchart TD
  SK[Shopkeeper] --> CAT[Create Categories]
  CAT --> PROD[Create Products]
  CAT --> SERV[Create Services]
  SK --> DISC[Create Discount Offers]
  SK --> RULES[Create Reward Rules]
  PROD --> ORDER[Create Order (Select customer + item + qty)]
  SERV --> ORDER
  DISC --> ORDER
  RULES --> ORDER
  ORDER --> DONE[Order saved + points earned]
```

## 5) Customer Flow (Discover → Earn Points)

```mermaid
flowchart TD
  CU[Customer] --> D[View Active Discounts]
  CU --> W[View Wallet Balance]
  CU --> O[View Orders]
  CU --> P[Purchase at Shop (offline/payment outside system)]
  P --> REC[Shopkeeper records Order]
  REC --> WAL[Wallet balance increases]
  REC --> LED[Ledger entry created]
```

## 6) Order Creation Sequence (Discount + Points + Wallet/Ledger)

```mermaid
sequenceDiagram
  participant SK as Shopkeeper UI
  participant OR as Orders Controller
  participant D as Discount Rules
  participant R as Reward Rules
  participant DB as Database
  participant W as Wallet/Ledger

  SK->>OR: Submit customer + item + qty
  OR->>DB: Load item (product/service)
  OR->>D: Load active discounts for shop
  D-->>OR: Matching discounts
  OR->>OR: Pick best discount amount
  OR->>R: Load active reward rules for shop
  R-->>OR: Matching reward rules
  OR->>OR: Pick best points earned
  OR->>DB: Create order + order item (transaction)
  OR->>W: Update wallet (+points), insert ledger entry
  OR-->>SK: Success / error
```

## 6A) Authentication Sequence (Protected Routes)

```mermaid
sequenceDiagram
  participant U as User Browser
  participant F as Auth Filter
  participant AU as Auth Controller
  participant C as Protected Controller

  U->>F: Request /dashboard (or /shopkeeper/*, /user/*)
  alt Not logged in
    F-->>U: Redirect /auth/login
    U->>AU: GET /auth/login
    AU-->>U: Login form
    U->>AU: POST credentials
    AU-->>U: Session created + redirect
  else Logged in
    F->>C: Allow request
    C-->>U: Render page
  end
```

## 6B) Admin Assigns Subscription to Shop

```mermaid
sequenceDiagram
  participant A as Admin UI
  participant SC as ShopSubscriptions Controller
  participant DB as Database

  A->>SC: Open "Shop Subscriptions"
  SC->>DB: Load shops + subscriptions + assignments
  DB-->>SC: Data set
  SC-->>A: Render list/form
  A->>SC: Submit assignment (shop, plan, dates)
  SC->>DB: Insert/Update rewarder_shop_subscriptions
  DB-->>SC: Success
  SC-->>A: Redirect with success message
```

## 6C) Shopkeeper Creates Discount Offer

```mermaid
sequenceDiagram
  participant SK as Shopkeeper UI
  participant DC as Discounts Controller
  participant DB as Database

  SK->>DC: Open /shopkeeper/discounts/add
  DC->>DB: Load shop context + categories/items
  DB-->>DC: Data set
  DC-->>SK: Render discount form
  SK->>DC: Submit rule (applies_to, type, value, window)
  DC->>DB: Insert rewarder_discounts
  DB-->>DC: Success
  DC-->>SK: Redirect to discounts list
```

## 6D) Customer Views Active Discounts

```mermaid
sequenceDiagram
  participant CU as Customer UI
  participant UC as User Discounts Controller
  participant DB as Database

  CU->>UC: GET /user/discounts
  UC->>DB: Query active discounts (status=1, within date window)
  DB-->>UC: Discounts + shop names
  UC-->>CU: Render discounts list
```

## 7) Discount Rule Decision (Best Discount Wins)

```mermaid
flowchart TD
  S[Start] --> L[Load active discounts for shop]
  L --> F1{Meets min_amount?}
  F1 -->|No| N1[Skip rule]
  F1 -->|Yes| F2{Matches applies_to target?}
  F2 -->|No| N1
  F2 -->|Yes| CALC[Compute discount amount]
  CALC --> CAP[Cap 0..subtotal]
  CAP --> BEST[Keep max discount amount]
  BEST --> END[Apply best discount only]
```

## 8) Reward Rule Decision (Best Points Wins)

```mermaid
flowchart TD
  S[Start] --> L[Load active reward rules for shop]
  L --> F{Matches applies_to target?}
  F -->|No| N[Skip rule]
  F -->|Yes| CALC[Compute points earned]
  CALC --> BEST[Keep max points]
  BEST --> END[Earn best points only]
```

## 9) Referral and QR/Link Purchase (Not Implemented Yet)

```mermaid
flowchart LR
  REF[Referral Mgmt] -.-> SYS[Rewarder System]
  QR[QR/Link Purchase Entry] -.-> SYS
  PAY[Online Payment Gateway] -.-> SYS

  NOTE[Not present in current codebase] --- REF
  NOTE --- QR
  NOTE --- PAY
```
