morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
5c6a2e78cf
TorbatYar/backend/services/loyalty
History
Mortezakoohjani 28f84b1274 Fix Loyalty production migrate: stamp head after create_all and relax DB host guard. 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-26 22:38:08 +03:30
..
alembic Ship Loyalty phases 7.2-7.6 (points through wallet) with production deploy. 2026-07-26 21:27:22 +03:30
app Fix Loyalty production migrate: stamp head after create_all and relax DB host guard. 2026-07-26 22:38:08 +03:30
scripts Fix Loyalty production migrate: stamp head after create_all and relax DB host guard. 2026-07-26 22:38:08 +03:30
alembic.ini Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
Dockerfile.dev Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
pytest-final.txt Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
pytest-heal.txt Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
pytest-out.txt Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
pytest.ini Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30
README.md Ship Loyalty phases 7.2-7.6 (points through wallet) with production deploy. 2026-07-26 21:27:22 +03:30
requirements.txt Sync platform docs, infra, and module services with Accounting integration. 2026-07-25 22:35:23 +03:30

README.md

Loyalty Service — Enterprise Loyalty Platform

Phase 7.6 Wallet complete (7.0–7.5 engines + immutable wallet ledger). Independent shared service — not part of CRM.

Reusable by Restaurant, Marketplace, Ecommerce, Academy, Booking, Healthcare, Salon, Gym, and future modules via API + Events only.

Ownership

Owns Does not own
LoyaltyProgram, MembershipTier, Member + lifecycle CRM sales entities
MembershipLifecycleEvent history Accounting / Posting Engine
PointAccount + immutable PointLedgerEntry Notification delivery
Reward catalog + RewardRedemption lifecycle Analytics store (later)
Campaign engine + applications Identity / Gift card UI (7.7+)
Referral programs / codes / attributions Payment gateway settlement
WalletAccount + immutable WalletLedgerEntry
Loyalty audit trail

Boundaries

  • Independent database: loyalty_db (ADR-001, ADR-011)
  • Row-level tenancy via tenant_id from request context (ADR-003)
  • Point and wallet balances come only from immutable ledgers — never mutate a balance column
  • Soft delete releases unique keys so codes can be reused; audit via /api/v1/audit
  • Inter-service communication: REST + Events only (transactional outbox)
  • Platform providers are contracts only under app/providers/
  • Route permissions enforced (loyalty.*); invalid X-Tenant-ID rejected

API Prefix

/api/v1 on port 8004

Resource Path
Programs /api/v1/programs
Tiers /api/v1/tiers
Members /api/v1/members
Point accounts /api/v1/point-accounts (+ ledger ops)
Rewards / Redemptions /api/v1/rewards, /api/v1/redemptions
Campaigns /api/v1/campaigns
Referrals /api/v1/referral-programs, /referral-codes, /referrals
Wallets /api/v1/wallets (+ /balance, /ledger, /credit, /debit, /adjust, /transfer)
Health /health

Permissions

loyalty.* including points, rewards, campaigns, referrals, wallets, audit trees.

Run locally

cd backend/services/loyalty
pip install -r requirements.txt
pytest -q
uvicorn app.main:app --port 8004 --reload

Related Documents