# System Overview

## Purpose

Rewarder is a multi-role management system for running shop promotions:

- Shopkeepers publish discount offers (fixed or percentage) for purchases, categories, or specific products/services.
- Customers receive reward points after purchases, which can be used for future discounts (wallet/ledger).
- Admin manages the master data (shops, categories, subscription plans) and platform configuration.

## Roles

- **Admin/Manager**: platform management (shops, subscriptions, reporting, permissions).
- **Shopkeeper**: manages their shop catalog, discount offers, reward rules, and records purchases (orders).
- **Customer**: views offers, views order history, and holds reward points in a wallet.
- **Guest**: can access the public landing page (`/`). The codebase does not expose a guest “offers list” route today.

## Core Concepts

- **Shop**: a merchant location (name/phone/address + optional city/category).
- **Subscription Plan**: master plan with price and duration; can be assigned to shops.
- **Discount Offer**: rule that reduces subtotal, scoped to ALL / category / item.
- **Reward Rule**: rule that earns points after purchase, scoped similarly to discounts.
- **Order**: recorded purchase; system stores subtotal, discount total, final total, and points earned.
- **Wallet**: customer’s current reward point balance.
- **Ledger**: immutable point transactions (earn/redemption history).

## What Is Implemented (Current Code)

The current codebase includes:

- Admin CRUD for subscriptions and shop subscriptions.
- Shopkeeper CRUD for products/services, discount rules, reward rules, and orders.
- Customer views for active discounts, wallet balance, and order history.
- Reward points earning (wallet + ledger writes) when an order is created.

Not present in the current codebase:

- Referral management (invite code, referred-by tracking, referral point rules).
- QR-code generation/scanning flows or purchase links.
- A payment gateway integration (orders are recorded as completed; payment is assumed offline/outside the system).

## Access Control (High Level)

Authentication is enforced globally with an exception for:

- `/`
- `/auth/*`

This is implemented via a global request filter (`authentication`) that redirects unauthenticated users to `/auth/login`.
