Date: 2026-02-05
Status: Sub-Phases 6.1–6.3 Complete, 6.4 In Progress
Branch: feature/member-services-foundation
Stats: 109 files, +11,388 lines | 18 commits | 88+ API endpoints
Phase 6 transforms Atlas from a transactional ERP into a customer engagement platform. It's not just loyalty points — it's a full member lifecycle system: registration → identification → rewards → retention → analytics.
Every feature is independently toggleable (Cardinal Rule #1), workflow-integrated (Cardinal Rule #2), and AI-queryable (Cardinal Rule #3).
┌─────────────────────────────────────────────────────────┐
│ Member Services Platform │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Member Core │ │ Loyalty │ │ Gift Vouchers │ │
│ │ Cards, OTPs │ │ Engine │ │ Issue/Redeem │ │
│ │ Config Flags │ │ Earn/Redeem │ │ Partial Use │ │
│ └──────┬───────┘ │ Expire/Gift │ │ GL Liability │ │
│ │ └──────┬───────┘ └──────┬────────┘ │
│ │ │ │ │
│ ┌──────┴─────┐ ┌───────┴──────┐ ┌───────┴────────┐ │
│ │ Tiers │ │ Referrals │ │ Paid Members │ │
│ │ Auto Up/Dn │ │ Codes+Track │ │ Plans+Billing │ │
│ └──────┬─────┘ └──────┬───────┘ └───────┬────────┘ │
│ │ │ │ │
│ ┌──────┴────────────────┴───────────────────┴────────┐ │
│ │ POS Integration Layer │ │
│ │ Verify → Benefits → Earn → Redeem → Vouchers │ │
│ └────────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌────────────────────────┴───────────────────────────┐ │
│ │ Portal APIs │ Engagement Campaigns │ Analytics │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Core member management + configuration system.
| Component | What It Does |
|---|---|
| Config Service | Feature flags for every module, registration channel toggles, member number format |
| Member Core | CRUD, search, status lifecycle (active/suspended/blocked/closed), customer linking |
| Member Cards | Physical + digital, auto-generate card numbers, QR data, block/replace |
| OTP System | Multi-channel (SMS/Email/WhatsApp), rate limiting, attempt tracking |
| Notification Prefs | Per-channel preferences, frequency settings, bulk update |
| POS Quick Register | Minimal fields (name + phone), auto-issue digital card |
| Bulk Import | CSV upload with per-row validation and error tracking |
Endpoints: 25 | Controllers: 6 | Services: 5
Full loyalty engine with multiple programs + gift voucher system.
| Component | What It Does |
|---|---|
| Loyalty Programs | Multiple programs per company, points/cashback/hybrid, configurable point names |
| Earning Rules | Per-spend/visit/product/category, 3 multiplier stacking modes (multiplicative/additive/highest) |
| Points Ledger | Immutable append-only ledger, balance reconciliation, full audit trail |
| Redemption Rules | Cash discount/product/service/voucher rewards, tier-gated, daily limits |
| Expiry Engine | 6 policy types (none/fixed/rolling/calendar_year/tier_based/partial_decay), batch processing |
| Point Transfer | Gift/transfer between members, daily limits, validation |
| Gift Voucher Types | Configurable templates, min/max amounts, reloadable, transferable |
| Gift Vouchers | Issue, partial redeem, reload, cancel, bulk issue, PIN protection |
| GL Integration | Earn → Dr Expense/Cr Liability · Redeem → Dr Liability/Cr Revenue · Expire → Dr Liability/Cr Breakage Income |
| Voucher GL | Issue → Dr Cash/Cr Liability · Redeem → Dr Liability/Cr Revenue · Expire → Breakage |
Endpoints: 32 | Controllers: 6 | Services: 8 (incl. 2 GL services)
Optional modules + full POS integration.
| Component | What It Does |
|---|---|
| Member Tiers | Configurable levels, 4 qualification types (points/lifetime/rolling 12mo/manual), auto-upgrade/downgrade, benefits JSONB |
| Tier History | Full audit of tier changes with reason tracking |
| Paid Memberships | Monthly/annual/lifetime plans, auto-renew, grace periods, billing stubs |
| Referral Program | Code generation, usage tracking, referrer + referee rewards, anti-fraud |
| POS Verify | Member lookup by card/phone/QR/OTP at point of sale |
| POS Benefits | Real-time tier discount + earning rate + loyalty balance for POS display |
| POS Earn/Redeem | Earn points from transaction, redeem at checkout |
| POS Vouchers | Sell, lookup balance, redeem gift vouchers at POS |
Endpoints: 31 | Controllers: 4 | Services: 3
Member-facing APIs + engagement campaigns + analytics dashboard.
| Component | What It Does |
|---|---|
| Portal Auth | Phone + OTP login for members (not staff auth) |
| Portal APIs | Profile, loyalty balance, tier, purchases, vouchers, referrals, digital card |
| Engagement Campaigns | Target by tier/status/activity, multi-channel dispatch, delivery tracking |
| Analytics | Dashboard stats, LTV, churn risk, tier distribution, voucher liability |
Expected Endpoints: ~30 | Building now
| Metric | Count |
|---|---|
| Total Files | 109 |
| Lines of Code | 11,388+ |
| API Endpoints | 88+ (118+ when 6.4 lands) |
| Database Tables | ~25 new |
| Enums | 21 |
| Models | ~25 |
| Services | 16+ |
| Controllers | 16 |
| GL Integration Points | 6 (earn, redeem, expire × loyalty + vouchers) |
-
Immutable Ledger — Points ledger is append-only. Voids create reversing entries, never delete. This is the source of truth; cached balances on enrollments are for performance only and reconciled nightly.
-
GL As First-Class Citizen — Every loyalty/voucher financial event creates journal entries. Points are a real liability on the balance sheet. Breakage (expired points/vouchers) is recognized as income.
-
Everything Optional — Each module (loyalty, tiers, paid memberships, referrals, vouchers) has a feature flag. A company can use just member management + POS integration without loyalty if they want.
-
POS-First — Member verification, benefit calculation, earn/redeem all designed for sub-second POS response times. Digital card QR for quick scan.
-
Multi-Program — A company can run multiple loyalty programs simultaneously (e.g., "Star Points" for retail + "Travel Miles" for hospitality).
- 6.4 completion — Portal APIs, engagement campaigns, analytics (in progress)
- Cardinal Rules Audit — After merge, full A+ compliance check
- Integration Tests — End-to-end flows (register → earn → redeem → expire)
- Phase 7+ — Promotions, Financial Reporting, Asset Management...