sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migrate module documentation to single source of truth

Browse Source 
Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2026-03-08 23:38:37 +01:00
parent 2287f4597d
commit f141cc4e6a
140 changed files with 19921 additions and 17723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
docs/proposals/loyalty-program-analysis.md
View File

@@ -1,387 +1,3 @@
# Loyalty Program Platform - Business Analysis
**Session Date:** 2026-01-13
**Status:** Initial Analysis - Pending Discussion
**Next Steps:** Resume discussion to clarify requirements
---
## Executive Summary
Multiple retailers have expressed interest in a loyalty program application. This document analyzes how the current OMS platform could be leveraged to provide a loyalty program offering as a new product line.
---
## Business Proposal Overview
### Concept
- **Multi-platform offering**: Different platform tiers (A, B, C) with varying feature sets
- **Target clients**: Merchants (retailers) with one or multiple shops
- **Core functionality**:
- Customer email collection
- Promotions and campaigns
- Discounts and rewards
- Points accumulation
### Platform Architecture Vision
```
┌─────────────────────────────────────────────────────────────────┐
│ PLATFORM LEVEL │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Platform A │ │ Platform B │ │ Platform C │ ... │
│ │ (Loyalty+) │ │ (Basic) │ │ (Enterprise) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ CLIENT LEVEL (Merchant) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Retailer X (e.g., Bakery Chain) │ │
│ │ ├── Shop 1 (Luxembourg City) │ │
│ │ ├── Shop 2 (Esch) │ │
│ │ └── Shop 3 (Differdange) │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ CUSTOMER LEVEL │
│ • Email collection • Points accumulation │
│ • Promotions/Offers • Discounts/Rewards │
│ • Purchase history • Tier status │
└─────────────────────────────────────────────────────────────────┘
```
---
## Current OMS Architecture Leverage
The existing platform has several components that map directly to loyalty program needs:
| Current OMS Component | Loyalty Program Use |
|-----------------------|---------------------|
| `Merchant` model | Client (retailer chain) |
| `Store` model | Individual shop/location |
| `Customer` model | Loyalty member base |
| `Order` model | Transaction for points calculation |
| `User` (store role) | Shop staff for check-in/redemption |
| Multi-tenant auth | Per-client data isolation |
| Admin dashboard | Retailer management interface |
| Store dashboard | Shop-level operations |
| API infrastructure | Integration capabilities |
### Existing Infrastructure Benefits
- Authentication & authorization system
- Multi-tenant data isolation
- Merchant → Store hierarchy
- Customer management
- Email/notification system (if exists)
- Celery background tasks
- API patterns established
---
## New Components Required
### 1. Core Loyalty Models
```python
# New database models needed
LoyaltyProgram
- id
- merchant_id (FK)
- name
- points_per_euro (Decimal)
- points_expiry_days (Integer, nullable)
- is_active (Boolean)
- settings (JSON) - flexible configuration
LoyaltyMember
- id
- customer_id (FK to existing Customer)
- loyalty_program_id (FK)
- points_balance (Integer)
- lifetime_points (Integer)
- tier_id (FK)
- enrolled_at (DateTime)
- last_activity_at (DateTime)
LoyaltyTier
- id
- loyalty_program_id (FK)
- name (e.g., "Bronze", "Silver", "Gold")
- min_points_required (Integer)
- benefits (JSON)
- sort_order (Integer)
LoyaltyTransaction
- id
- member_id (FK)
- store_id (FK) - which shop
- transaction_type (ENUM: earn, redeem, expire, adjust)
- points (Integer, positive or negative)
- reference_type (e.g., "order", "promotion", "manual")
- reference_id (Integer, nullable)
- description (String)
- created_at (DateTime)
- created_by_user_id (FK, nullable)
Promotion
- id
- loyalty_program_id (FK)
- name
- description
- promotion_type (ENUM: bonus_points, discount_percent, discount_fixed, free_item)
- value (Decimal)
- conditions (JSON) - min spend, specific products, etc.
- start_date (DateTime)
- end_date (DateTime)
- max_redemptions (Integer, nullable)
- is_active (Boolean)
PromotionRedemption
- id
- promotion_id (FK)
- member_id (FK)
- store_id (FK)
- redeemed_at (DateTime)
- order_id (FK, nullable)
Reward
- id
- loyalty_program_id (FK)
- name
- description
- points_cost (Integer)
- reward_type (ENUM: discount, free_product, voucher)
- value (Decimal or JSON)
- is_active (Boolean)
- stock (Integer, nullable) - for limited rewards
```
### 2. Platform Offering Tiers
```python
# Platform-level configuration
class PlatformOffering(Enum):
BASIC = "basic"
PLUS = "plus"
ENTERPRISE = "enterprise"
# Feature matrix per offering
OFFERING_FEATURES = {
"basic": {
"max_shops": 1,
"points_earning": True,
"basic_promotions": True,
"tiers": False,
"custom_rewards": False,
"api_access": False,
"white_label": False,
"analytics": "basic",
},
"plus": {
"max_shops": 10,
"points_earning": True,
"basic_promotions": True,
"tiers": True,
"custom_rewards": True,
"api_access": False,
"white_label": False,
"analytics": "advanced",
},
"enterprise": {
"max_shops": None, # Unlimited
"points_earning": True,
"basic_promotions": True,
"tiers": True,
"custom_rewards": True,
"api_access": True,
"white_label": True,
"analytics": "full",
},
}
```
### 3. Feature Matrix
| Feature | Basic | Plus | Enterprise |
|---------|:-----:|:----:|:----------:|
| Customer email collection | ✓ | ✓ | ✓ |
| Points earning | ✓ | ✓ | ✓ |
| Basic promotions | ✓ | ✓ | ✓ |
| Multi-shop support | 1 shop | Up to 10 | Unlimited |
| Tier system (Bronze/Silver/Gold) | - | ✓ | ✓ |
| Custom rewards catalog | - | ✓ | ✓ |
| API access | - | - | ✓ |
| White-label branding | - | - | ✓ |
| Analytics dashboard | Basic | Advanced | Full |
| Customer segmentation | - | ✓ | ✓ |
| Email campaigns | - | ✓ | ✓ |
| Dedicated support | - | - | ✓ |
---
## Implementation Options
### Option A: Standalone Application
- Separate codebase
- Shares database patterns but independent deployment
- **Pros**: Clean separation, can scale independently
- **Cons**: Duplication of auth, admin patterns; more maintenance
### Option B: Module in Current OMS (Recommended)
- Add loyalty as a feature module within existing platform
- Leverages existing infrastructure
**Proposed directory structure:**
```
letzshop-product-import/
├── app/
│ ├── api/v1/
│ │ ├── loyalty/ # NEW
│ │ │ ├── __init__.py
│ │ │ ├── programs.py # Program CRUD
│ │ │ ├── members.py # Member management
│ │ │ ├── transactions.py # Points transactions
│ │ │ ├── promotions.py # Promotion management
│ │ │ ├── rewards.py # Rewards catalog
│ │ │ └── public.py # Customer-facing endpoints
│ │ │
│ ├── services/
│ │ ├── loyalty/ # NEW
│ │ │ ├── __init__.py
│ │ │ ├── points_service.py # Points calculation logic
│ │ │ ├── tier_service.py # Tier management
│ │ │ ├── promotion_service.py # Promotion rules engine
│ │ │ └── reward_service.py # Reward redemption
│ │ │
│ ├── templates/
│ │ ├── loyalty/ # NEW - if web UI needed
│ │ │ ├── admin/ # Platform admin views
│ │ │ ├── retailer/ # Retailer dashboard
│ │ │ └── member/ # Customer-facing portal
│ │ │
├── models/
│ ├── database/
│ │ ├── loyalty.py # NEW - All loyalty models
│ ├── schema/
│ │ ├── loyalty.py # NEW - Pydantic schemas
```
---
## Open Questions (To Discuss)
### 1. Points Model
- **Q1.1**: Fixed points per euro spent? (e.g., 1 point = €0.10 spent)
- **Q1.2**: Variable points by product category? (e.g., 2x points on bakery items)
- **Q1.3**: Bonus points for specific actions? (e.g., sign-up bonus, birthday bonus)
- **Q1.4**: Points expiration policy? (e.g., expire after 12 months of inactivity)
### 2. Redemption Methods
- **Q2.1**: In-store redemption only? (requires POS integration or staff app)
- **Q2.2**: Online shop redemption?
- **Q2.3**: Both in-store and online?
- **Q2.4**: What POS systems do target retailers use?
### 3. Customer Identification
- **Q3.1**: Email only?
- **Q3.2**: Phone number as alternative?
- **Q3.3**: Physical loyalty card with barcode/QR?
- **Q3.4**: Mobile app with digital card?
- **Q3.5**: Integration with existing customer accounts?
### 4. Multi-Platform Architecture
- **Q4.1**: Different domains per offering tier?
- e.g., loyalty-basic.lu, loyalty-pro.lu, loyalty-enterprise.lu
- **Q4.2**: Same domain with feature flags based on subscription?
- **Q4.3**: White-label with custom domains for enterprise clients?
### 5. Data & Privacy
- **Q5.1**: Can retailers see each other's customers? (Assumed: No)
- **Q5.2**: Can a customer be enrolled in multiple loyalty programs? (Different retailers)
- **Q5.3**: GDPR considerations for customer data?
- **Q5.4**: Data export/portability requirements?
### 6. Business Model
- **Q6.1**: Pricing model? (Monthly subscription, per-transaction fee, hybrid?)
- **Q6.2**: Free trial period?
- **Q6.3**: Upgrade/downgrade path between tiers?
### 7. Integration Requirements
- **Q7.1**: POS system integrations needed?
- **Q7.2**: Email marketing platform integration? (Mailchimp, SendGrid, etc.)
- **Q7.3**: SMS notifications?
- **Q7.4**: Accounting/invoicing integration?
### 8. MVP Scope
- **Q8.1**: What is the minimum viable feature set for first launch?
- **Q8.2**: Which offering tier to build first?
- **Q8.3**: Target timeline?
- **Q8.4**: Pilot retailers identified?
---
## Potential User Flows
### Retailer Onboarding Flow
1. Retailer signs up on platform
2. Selects offering tier (Basic/Plus/Enterprise)
3. Configures loyalty program (name, points ratio, branding)
4. Adds shop locations
5. Invites staff members
6. Sets up initial promotions
7. Goes live
### Customer Enrollment Flow
1. Customer visits shop or website
2. Provides email (and optionally phone)
3. Receives welcome email with member ID/card
4. Starts earning points on purchases
### Points Earning Flow (In-Store)
1. Customer makes purchase
2. Staff asks for loyalty member ID (email, phone, or card scan)
3. System calculates points based on purchase amount
4. Points credited to member account
5. Receipt shows points earned and balance
### Reward Redemption Flow
1. Customer views available rewards (app/web/in-store)
2. Selects reward to redeem
3. System validates sufficient points
4. Generates redemption code/voucher
5. Customer uses at checkout
6. Points deducted from balance
---
## Next Steps
1. **Clarify requirements** - Answer open questions above
2. **Define MVP scope** - What's the minimum for first launch?
3. **Technical design** - Database schema, API design
4. **UI/UX design** - Retailer dashboard, customer portal
5. **Implementation plan** - Phased approach
6. **Pilot program** - Identify first retailers for beta
---
## Session Notes
### 2026-01-13
- Initial business proposal discussion
- Analyzed current OMS architecture fit
- Identified reusable components
- Outlined new models needed
- Documented open questions
- **Action**: Resume discussion to clarify requirements
---
*Document created for session continuity. Update as discussions progress.*
This document has moved to the loyalty module docs: [Program Analysis](../modules/loyalty/program-analysis.md)