History

Mortezakoohjani e41ecfad4c Sync platform docs, infra, and module services with Accounting integration. Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>		2026-07-25 22:35:23 +03:30
..
alembic	Sync platform docs, infra, and module services with Accounting integration.	2026-07-25 22:35:23 +03:30
app	Sync platform docs, infra, and module services with Accounting integration.	2026-07-25 22:35:23 +03:30
scripts	Sync platform docs, infra, and module services with Accounting integration.	2026-07-25 22:35:23 +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	Sync platform docs, infra, and module services with Accounting integration.	2026-07-25 22:35:23 +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.1 Membership Engine complete (foundation 7.0 + lifecycle). 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 shell (no mutable balance)	Notification delivery
Reward catalog shell	Analytics store (later)
Campaign shell (versioned rules later)	Identity / Wallet UI / Gift card engine (later phases)
Loyalty audit trail

Boundaries

Independent database: loyalty_db (ADR-001, ADR-011)
Row-level tenancy via tenant_id from request context (ADR-003)
Membership lifecycle transitions validated in MembershipEngineService
Program soft-delete rejected while blocking members exist
Direct balance modification is prohibited — ledger in Phase 7.2
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

Structure

app/
  api/v1/          # Loyalty HTTP APIs only
  models/          # foundation aggregates
  repositories/
  services/
  validators/
  schemas/
  events/
  permissions/
  providers/
  tests/
alembic/versions/0001_initial.py

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`
Rewards	`/api/v1/rewards`
Campaigns	`/api/v1/campaigns`
Health	`/health`

Permissions

loyalty.* including loyalty.programs.*, loyalty.tiers.*, loyalty.members.*, loyalty.point_accounts.*, loyalty.rewards.*, loyalty.campaigns.*, loyalty.audit.*

Run locally

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