# jvillatox/loyaltyos architecture

> Architecture diagram of the GitHub repository jvillatox/loyaltyos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jvillatox/loyaltyos
- Repository: https://github.com/jvillatox/loyaltyos

## Overview

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: [`apps/api/src/app.ts`](https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/app.ts) (Fastify REST API), [`packages/core/src/service.ts`](https://github.com/jvillatox/loyaltyos/blob/main/packages/core/src/service.ts) (Points ledger engine), [`packages/coalition/src/service.ts`](https://github.com/jvillatox/loyaltyos/blob/main/packages/coalition/src/service.ts) (Coalition operations), [`packages/campaigns/src/service.ts`](https://github.com/jvillatox/loyaltyos/blob/main/packages/campaigns/src/service.ts) (Campaign evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_admin["Admin dashboard<br/>[App.tsx]"]
  node_portal["Customer portal<br/>[App.tsx]"]
  node_widget["Loyalty widget<br/>[loyalty-widget.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
end

subgraph group_api["API and access"]
  node_api["Fastify REST API<br/>[app.ts]"]
  node_access["Authentication and RBAC<br/>[auth.ts]"]
  node_error_handling["API error mapping<br/>[error-handler.ts]"]
end

subgraph group_loyalty["Loyalty services"]
  node_points["Points ledger engine<br/>[service.ts]"]
  node_coalition["Coalition operations<br/>[service.ts]"]
end

subgraph group_engagement["Engagement features"]
  node_campaigns["Campaign evaluation<br/>[service.ts]"]
  node_coupons["Coupon management<br/>[service.ts]"]
  node_segments["Member segmentation<br/>[service.ts]"]
  node_badges_tiers["Badges and tiers<br/>[badges-service.ts]"]
  node_rewards["Reward redemption<br/>[service.ts]"]
  node_giftcards["Gift card operations<br/>[service.ts]"]
  node_notifications["Notifications<br/>[service.ts]"]
end

subgraph group_infrastructure["State and integrations"]
  node_apprecio["Apprecio adapter<br/>[apprecio.ts]"]
  node_postgres[("PostgreSQL")]
  node_redis_queue["Redis and job queues<br/>[queue.ts]"]
  node_notification_providers["Notification providers<br/>[provider.ts]"]
end

node_api_consumer(("External API client"))

node_admin -->|"calls REST"| node_api
node_portal -->|"calls REST"| node_api
node_widget -->|"calls REST"| node_api
node_api_consumer -->|"calls REST"| node_api
node_mcp -.->|"accesses API"| node_api
node_api -->|"applies"| node_access
node_api -->|"maps errors"| node_error_handling
node_access -->|"authorizes access"| node_points
node_points -->|"evaluates events"| node_campaigns
node_points -->|"triggers"| node_notifications
node_points -->|"supports"| node_badges_tiers
node_points -->|"coordinates"| node_coalition
node_api -.->|"serves coupon routes"| node_coupons
node_api -.->|"serves segment routes"| node_segments
node_api -.->|"serves reward routes"| node_rewards
node_api -.->|"serves gift card routes"| node_giftcards
node_campaigns -->|"uses points service"| node_points
node_rewards -->|"uses points service"| node_points
node_coalition -->|"uses points service"| node_points
node_coalition -.->|"dispatches operations"| node_apprecio
node_points -->|"persists ledger"| node_postgres
node_campaigns -.->|"persists campaigns"| node_postgres
node_giftcards -.->|"persists cards"| node_postgres
node_badges_tiers -.->|"persists badges"| node_postgres
node_notifications -->|"sends through"| node_notification_providers
node_notification_providers -.->|"dispatches jobs"| node_redis_queue
node_points -.->|"uses queues"| node_redis_queue

click node_admin "https://github.com/jvillatox/loyaltyos/blob/main/apps/admin/src/App.tsx"
click node_portal "https://github.com/jvillatox/loyaltyos/blob/main/apps/portal/src/App.tsx"
click node_widget "https://github.com/jvillatox/loyaltyos/blob/main/apps/widget/src/components/loyalty-widget.ts"
click node_mcp "https://github.com/jvillatox/loyaltyos/blob/main/apps/mcp-server/src/server.ts"
click node_api "https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/app.ts"
click node_access "https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/plugins/auth.ts"
click node_error_handling "https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/lib/error-handler.ts"
click node_points "https://github.com/jvillatox/loyaltyos/blob/main/packages/core/src/service.ts"
click node_campaigns "https://github.com/jvillatox/loyaltyos/blob/main/packages/campaigns/src/service.ts"
click node_coupons "https://github.com/jvillatox/loyaltyos/blob/main/packages/coupons/src/service.ts"
click node_segments "https://github.com/jvillatox/loyaltyos/blob/main/packages/segments/src/service.ts"
click node_badges_tiers "https://github.com/jvillatox/loyaltyos/blob/main/packages/badges/src/badges-service.ts"
click node_rewards "https://github.com/jvillatox/loyaltyos/blob/main/packages/rewards/src/service.ts"
click node_giftcards "https://github.com/jvillatox/loyaltyos/blob/main/packages/giftcards/src/service.ts"
click node_notifications "https://github.com/jvillatox/loyaltyos/blob/main/packages/notifications/src/service.ts"
click node_coalition "https://github.com/jvillatox/loyaltyos/blob/main/packages/coalition/src/service.ts"
click node_apprecio "https://github.com/jvillatox/loyaltyos/blob/main/packages/coalition/src/adapters/apprecio.ts"
click node_redis_queue "https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/lib/queue.ts"
click node_notification_providers "https://github.com/jvillatox/loyaltyos/blob/main/packages/notifications/src/provider.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_admin,node_portal,node_widget,node_mcp,node_api_consumer toneBlue
class node_api,node_access,node_error_handling toneAmber
class node_points,node_coalition toneMint
class node_campaigns,node_coupons,node_segments,node_badges_tiers,node_rewards,node_giftcards,node_notifications toneRose
class node_apprecio,node_postgres,node_redis_queue,node_notification_providers toneIndigo
```

## Components

### Client applications

- [Admin dashboard](https://github.com/jvillatox/loyaltyos/blob/main/apps/admin/src/App.tsx): `apps/admin/src/App.tsx`
- [Customer portal](https://github.com/jvillatox/loyaltyos/blob/main/apps/portal/src/App.tsx): `apps/portal/src/App.tsx`
- [Loyalty widget](https://github.com/jvillatox/loyaltyos/blob/main/apps/widget/src/components/loyalty-widget.ts): `apps/widget/src/components/loyalty-widget.ts`
- [MCP server](https://github.com/jvillatox/loyaltyos/blob/main/apps/mcp-server/src/server.ts): `apps/mcp-server/src/server.ts`

### API and access

- [Fastify REST API](https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication and RBAC](https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/plugins/auth.ts): `apps/api/src/plugins/auth.ts`
- [API error mapping](https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/lib/error-handler.ts): `apps/api/src/lib/error-handler.ts`

### Loyalty services

- [Points ledger engine](https://github.com/jvillatox/loyaltyos/blob/main/packages/core/src/service.ts): `packages/core/src/service.ts`
- [Coalition operations](https://github.com/jvillatox/loyaltyos/blob/main/packages/coalition/src/service.ts): `packages/coalition/src/service.ts`

### Engagement features

- [Campaign evaluation](https://github.com/jvillatox/loyaltyos/blob/main/packages/campaigns/src/service.ts): `packages/campaigns/src/service.ts`
- [Coupon management](https://github.com/jvillatox/loyaltyos/blob/main/packages/coupons/src/service.ts): `packages/coupons/src/service.ts`
- [Member segmentation](https://github.com/jvillatox/loyaltyos/blob/main/packages/segments/src/service.ts): `packages/segments/src/service.ts`
- [Badges and tiers](https://github.com/jvillatox/loyaltyos/blob/main/packages/badges/src/badges-service.ts): `packages/badges/src/badges-service.ts`
- [Reward redemption](https://github.com/jvillatox/loyaltyos/blob/main/packages/rewards/src/service.ts): `packages/rewards/src/service.ts`
- [Gift card operations](https://github.com/jvillatox/loyaltyos/blob/main/packages/giftcards/src/service.ts): `packages/giftcards/src/service.ts`
- [Notifications](https://github.com/jvillatox/loyaltyos/blob/main/packages/notifications/src/service.ts): `packages/notifications/src/service.ts`

### State and integrations

- [Apprecio adapter](https://github.com/jvillatox/loyaltyos/blob/main/packages/coalition/src/adapters/apprecio.ts): `packages/coalition/src/adapters/apprecio.ts`
- **PostgreSQL**
- [Redis and job queues](https://github.com/jvillatox/loyaltyos/blob/main/apps/api/src/lib/queue.ts): `apps/api/src/lib/queue.ts`
- [Notification providers](https://github.com/jvillatox/loyaltyos/blob/main/packages/notifications/src/provider.ts): `packages/notifications/src/provider.ts`

### Other components

- **External API client**

## Connections

- Admin dashboard → Fastify REST API: calls REST (evidence: `README.md`)
- Customer portal → Fastify REST API: calls REST (evidence: `README.md`)
- Loyalty widget → Fastify REST API: calls REST (evidence: `README.md`)
- External API client → Fastify REST API: calls REST (evidence: `README.md`)
- MCP server → Fastify REST API: accesses API
- Fastify REST API → Authentication and RBAC: applies (evidence: `README.md`)
- Fastify REST API → API error mapping: maps errors (evidence: `apps/api/src/app.ts`)
- Authentication and RBAC → Points ledger engine: authorizes access (evidence: `README.md`)
- Points ledger engine → Campaign evaluation: evaluates events (evidence: `README.md`)
- Points ledger engine → Notifications: triggers (evidence: `README.md`)
- Points ledger engine → Badges and tiers: supports (evidence: `README.md`)
- Points ledger engine → Coalition operations: coordinates (evidence: `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 (evidence: `packages/campaigns/src/service.ts`)
- Reward redemption → Points ledger engine: uses points service (evidence: `packages/rewards/src/service.ts`)
- Coalition operations → Points ledger engine: uses points service (evidence: `packages/coalition/src/service.ts`)
- Coalition operations → Apprecio adapter: dispatches operations
- Points ledger engine → PostgreSQL: persists ledger (evidence: `README.md`)
- Campaign evaluation → PostgreSQL: persists campaigns
- Gift card operations → PostgreSQL: persists cards
- Badges and tiers → PostgreSQL: persists badges
- Notifications → Notification providers: sends through (evidence: `packages/notifications/src/service.ts`)
- Notification providers → Redis and job queues: dispatches jobs
- Points ledger engine → Redis and job queues: uses queues