# 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

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

## Related Documents

- [Phase 7.0](../../../docs/loyalty-phase-7-0.md)
- [Module Registry](../../../docs/module-registry.md#loyalty)
- [ADR-011](../../../docs/architecture/adr/ADR-011.md)
- [Architecture](../../../docs/architecture/architecture.md)