How jvillatox/loyaltyos works
LoyaltyOS is an API-first, multi-tenant loyalty platform. Clients authenticate and use the REST API to manage programs, members, points, campaigns, and engagement features; customers also use a portal and embeddable widget. The core points engine maintains ledger operations, while coalition operations connect to external providers. The graph reflects README-described architecture and sampled imports/calls; several API routes and subsystems were not inspected, so their internal wiring is shown only where documented.
Main entry points: app.ts Fastify REST API · src/service.ts Points ledger engine · src/service.ts Coalition operations · src/service.ts Campaign evaluation
Components 21
Client applications
- Admin dashboard
apps/admin/src/App.tsx - Customer portal
apps/portal/src/App.tsx - Loyalty widget
apps/widget/src/components/loyalty-widget.ts - MCP server
apps/mcp-server/src/server.ts
API and access
- Fastify REST API
apps/api/src/app.ts - Authentication and RBAC
apps/api/src/plugins/auth.ts - API error mapping
apps/api/src/lib/error-handler.ts
Loyalty services
- Points ledger engine
packages/core/src/service.ts - Coalition operations
packages/coalition/src/service.ts
Engagement features
- Campaign evaluation
packages/campaigns/src/service.ts - Coupon management
packages/coupons/src/service.ts - Member segmentation
packages/segments/src/service.ts - Badges and tiers
packages/badges/src/badges-service.ts - Reward redemption
packages/rewards/src/service.ts - Gift card operations
packages/giftcards/src/service.ts - Notifications
packages/notifications/src/service.ts
State and integrations
- Apprecio adapter
packages/coalition/src/adapters/apprecio.ts - PostgreSQL
- Redis and job queues
apps/api/src/lib/queue.ts - Notification providers
packages/notifications/src/provider.ts
Other components
- External API client
Connections 27
- Admin dashboard → Fastify REST API: calls REST
README.md - Customer portal → Fastify REST API: calls REST
README.md - Loyalty widget → Fastify REST API: calls REST
README.md - External API client → Fastify REST API: calls REST
README.md - MCP server → Fastify REST API: accesses API
- Fastify REST API → Authentication and RBAC: applies
README.md - Fastify REST API → API error mapping: maps errors
apps/api/src/app.ts - Authentication and RBAC → Points ledger engine: authorizes access
README.md - Points ledger engine → Campaign evaluation: evaluates events
README.md - Points ledger engine → Notifications: triggers
README.md - Points ledger engine → Badges and tiers: supports
README.md - Points ledger engine → Coalition operations: coordinates
README.md - Fastify REST API → Coupon management: serves coupon routes
- Fastify REST API → Member segmentation: serves segment routes
- Fastify REST API → Reward redemption: serves reward routes
- Fastify REST API → Gift card operations: serves gift card routes
- Campaign evaluation → Points ledger engine: uses points service
packages/campaigns/src/service.ts - Reward redemption → Points ledger engine: uses points service
packages/rewards/src/service.ts - Coalition operations → Points ledger engine: uses points service
packages/coalition/src/service.ts - Coalition operations → Apprecio adapter: dispatches operations
- Points ledger engine → PostgreSQL: persists ledger
README.md - Campaign evaluation → PostgreSQL: persists campaigns
- Gift card operations → PostgreSQL: persists cards
- Badges and tiers → PostgreSQL: persists badges
- Notifications → Notification providers: sends through
packages/notifications/src/service.ts - Notification providers → Redis and job queues: dispatches jobs
- Points ledger engine → Redis and job queues: uses queues