# ali00209/loyaltypointssaas architecture

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

- Interactive diagram: https://gitdiagram.com/ali00209/loyaltypointssaas
- Repository: https://github.com/ali00209/loyaltypointssaas

## Overview

This is a multi-tenant loyalty and rewards platform: business operators configure programs and manage customers, products, and rules; customer or POS events earn points, which can later be redeemed, while dashboards and billing support ongoing operations. The clearest sampled runtime path is event submission through principal resolution, validation, customer lookup, and points application. The repository also contains customer portals, analytics, and platform billing/admin areas; their implementation paths are visible in the tree, but their internal wiring was not sampled.

Main entry points: [`src/db/index.ts`](https://github.com/ali00209/loyaltypointssaas/blob/main/src/db/index.ts) (PostgreSQL database), [`src/lib/api-guard.ts`](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/api-guard.ts) (Identity and access), [`src/lib/rules.ts`](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/rules.ts) (Event catalog and rules), [`src/app/api/redemption-rules/route.ts`](https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/redemption-rules/route.ts) (Redemption rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Business operations"]
  node_ledger["Program dashboard<br/>[AppLedgerPage.tsx]"]
  node_catalog["Products and customers"]
  node_rule_ui["Rule editor"]
  node_rule_api["Rule management<br/>[route.ts]"]
  node_redemption_rules["Redemption rules<br/>[route.ts]"]
  node_analytics["Program analytics<br/>[route.ts]"]
end

subgraph group_loyalty["Loyalty engine"]
  node_event_api["Loyalty event intake<br/>[route.ts]"]
  node_event_rules["Event catalog and rules<br/>[rules.ts]"]
  node_points["Points processing<br/>[points.ts]"]
  node_redemption["Redemption processing<br/>[redemption.ts]"]
  node_rule_builder["Rule construction<br/>[rule-builder.ts]"]
  node_rule_sentence["Rule descriptions<br/>[ruleSentence.ts]"]
end

subgraph group_customer["Customer experience"]
  node_customer_portal["Customer portal"]
  node_customer_api["Customer services"]
end

subgraph group_platform["Platform services"]
  node_billing["Subscriptions and invoices"]
  node_admin["Platform administration"]
  node_api_client["Web API client<br/>[client.ts]"]
  node_api_modules["Web API modules"]
  node_guard["Identity and access<br/>[api-guard.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_query_hooks["Client query hooks<br/>[hooks.ts]"]
  node_query_index["Query exports<br/>[index.ts]"]
end

subgraph group_data["Persistence"]
  node_database[("PostgreSQL database<br/>[index.ts]")]
  node_schema["Domain schema<br/>[schema.ts]"]
end

node_operator(("Program operator"))

node_operator -->|"uses"| node_ledger
node_ledger -->|"requests data"| node_api_modules
node_ledger -->|"uses hooks"| node_query_index
node_rule_ui -->|"renders rules"| node_rule_sentence
node_rule_api -->|"checks access"| node_guard
node_rule_api -->|"uses"| node_rule_builder
node_rule_api -->|"uses"| node_event_rules
node_redemption_rules -->|"checks access"| node_guard
node_redemption_rules -->|"validates rules"| node_redemption
node_redemption_rules -->|"reads and writes"| node_database
node_redemption_rules -->|"uses tables"| node_schema
node_event_api -->|"resolves principal"| node_guard
node_event_api -->|"checks event"| node_event_rules
node_event_api -->|"applies event"| node_points
node_event_api -->|"looks up customer"| node_database
node_points -->|"evaluates rules"| node_event_rules
node_points -->|"records points"| node_database
node_points -->|"uses tables"| node_schema
node_rule_builder -->|"uses"| node_event_rules
node_customer_portal -.->|"loads portal data"| node_customer_api
node_analytics -->|"checks access"| node_guard
node_analytics -->|"queries data"| node_database
node_api_modules -->|"uses client"| node_api_client
node_api_client -.->|"sends HTTP requests"| node_customer_api
node_query_index -->|"exports hooks"| node_query_hooks
node_guard -->|"resolves identity"| node_auth
node_auth -->|"reads identity records"| node_database
node_database -->|"configures ORM"| node_schema
node_schema -->|"uses rule types"| node_event_rules

click node_ledger "https://github.com/ali00209/loyaltypointssaas/blob/main/src/components/AppLedgerPage.tsx"
click node_catalog "https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api"
click node_rule_ui "https://github.com/ali00209/loyaltypointssaas/blob/main/src/components/ConditionSentenceEditor.tsx"
click node_rule_api "https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/rules/route.ts"
click node_redemption_rules "https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/redemption-rules/route.ts"
click node_event_api "https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/events/route.ts"
click node_event_rules "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/rules.ts"
click node_points "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/points.ts"
click node_redemption "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/redemption.ts"
click node_rule_builder "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/rule-builder.ts"
click node_rule_sentence "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/ruleSentence.ts"
click node_customer_portal "https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/p/%5Bslug%5D"
click node_customer_api "https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/customer"
click node_analytics "https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/analytics/route.ts"
click node_billing "https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/billing"
click node_admin "https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/admin"
click node_api_client "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/api/client.ts"
click node_api_modules "https://github.com/ali00209/loyaltypointssaas/tree/main/src/lib/api"
click node_guard "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/api-guard.ts"
click node_auth "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/auth.ts"
click node_database "https://github.com/ali00209/loyaltypointssaas/blob/main/src/db/index.ts"
click node_schema "https://github.com/ali00209/loyaltypointssaas/blob/main/src/db/schema.ts"
click node_query_hooks "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/query/hooks.ts"
click node_query_index "https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/query/index.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_ledger,node_catalog,node_rule_ui,node_rule_api,node_redemption_rules,node_analytics toneBlue
class node_event_api,node_event_rules,node_points,node_redemption,node_rule_builder,node_rule_sentence toneAmber
class node_customer_portal,node_customer_api toneMint
class node_billing,node_admin,node_api_client,node_api_modules,node_guard,node_auth,node_query_hooks,node_query_index toneRose
class node_database,node_schema,node_operator toneIndigo
```

## Components

### Business operations

- [Program dashboard](https://github.com/ali00209/loyaltypointssaas/blob/main/src/components/AppLedgerPage.tsx): `src/components/AppLedgerPage.tsx`
- [Products and customers](https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api): `src/app/api`
- [Rule editor](https://github.com/ali00209/loyaltypointssaas/blob/main/src/components/ConditionSentenceEditor.tsx): `src/components/ConditionSentenceEditor.tsx`
- [Rule management](https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/rules/route.ts): `src/app/api/rules/route.ts`
- [Redemption rules](https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/redemption-rules/route.ts): `src/app/api/redemption-rules/route.ts`
- [Program analytics](https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/analytics/route.ts): `src/app/api/analytics/route.ts`

### Loyalty engine

- [Loyalty event intake](https://github.com/ali00209/loyaltypointssaas/blob/main/src/app/api/events/route.ts): `src/app/api/events/route.ts`
- [Event catalog and rules](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/rules.ts): `src/lib/rules.ts`
- [Points processing](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/points.ts): `src/lib/points.ts`
- [Redemption processing](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/redemption.ts): `src/lib/redemption.ts`
- [Rule construction](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/rule-builder.ts): `src/lib/rule-builder.ts`
- [Rule descriptions](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/ruleSentence.ts): `src/lib/ruleSentence.ts`

### Customer experience

- [Customer portal](https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/p/%5Bslug%5D): `src/app/p/[slug]`
- [Customer services](https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/customer): `src/app/api/customer`

### Platform services

- [Subscriptions and invoices](https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/billing): `src/app/api/billing`
- [Platform administration](https://github.com/ali00209/loyaltypointssaas/tree/main/src/app/api/admin): `src/app/api/admin`
- [Web API client](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/api/client.ts): `src/lib/api/client.ts`
- [Web API modules](https://github.com/ali00209/loyaltypointssaas/tree/main/src/lib/api): `src/lib/api`
- [Identity and access](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/api-guard.ts): `src/lib/api-guard.ts`
- [Authentication](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Client query hooks](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/query/hooks.ts): `src/lib/query/hooks.ts`
- [Query exports](https://github.com/ali00209/loyaltypointssaas/blob/main/src/lib/query/index.ts): `src/lib/query/index.ts`

### Persistence

- [PostgreSQL database](https://github.com/ali00209/loyaltypointssaas/blob/main/src/db/index.ts): `src/db/index.ts`
- [Domain schema](https://github.com/ali00209/loyaltypointssaas/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **Program operator**

## Connections

- Program operator → Program dashboard: uses
- Program dashboard → Web API modules: requests data (evidence: `src/components/AppLedgerPage.tsx`)
- Program dashboard → Query exports: uses hooks (evidence: `src/components/AppLedgerPage.tsx`)
- Rule editor → Rule descriptions: renders rules (evidence: `src/components/ConditionSentenceEditor.tsx`)
- Rule management → Identity and access: checks access (evidence: `src/app/api/rules/route.ts`)
- Rule management → Rule construction: uses (evidence: `src/app/api/rules/route.ts`)
- Rule management → Event catalog and rules: uses (evidence: `src/app/api/rules/route.ts`)
- Redemption rules → Identity and access: checks access (evidence: `src/app/api/redemption-rules/route.ts`)
- Redemption rules → Redemption processing: validates rules (evidence: `src/app/api/redemption-rules/route.ts`)
- Redemption rules → PostgreSQL database: reads and writes (evidence: `src/app/api/redemption-rules/route.ts`)
- Redemption rules → Domain schema: uses tables (evidence: `src/app/api/redemption-rules/route.ts`)
- Loyalty event intake → Identity and access: resolves principal (evidence: `src/app/api/events/route.ts`)
- Loyalty event intake → Event catalog and rules: checks event (evidence: `src/app/api/events/route.ts`)
- Loyalty event intake → Points processing: applies event (evidence: `src/app/api/events/route.ts`)
- Loyalty event intake → PostgreSQL database: looks up customer (evidence: `src/app/api/events/route.ts`)
- Points processing → Event catalog and rules: evaluates rules (evidence: `src/lib/points.ts`)
- Points processing → PostgreSQL database: records points (evidence: `src/lib/points.ts`)
- Points processing → Domain schema: uses tables (evidence: `src/lib/points.ts`)
- Rule construction → Event catalog and rules: uses (evidence: `src/lib/rule-builder.ts`)
- Customer portal → Customer services: loads portal data
- Program analytics → Identity and access: checks access (evidence: `src/app/api/analytics/route.ts`)
- Program analytics → PostgreSQL database: queries data (evidence: `src/app/api/analytics/route.ts`)
- Web API modules → Web API client: uses client (evidence: `src/lib/api/index.ts`)
- Web API client → Customer services: sends HTTP requests
- Query exports → Client query hooks: exports hooks (evidence: `src/lib/query/index.ts`)
- Identity and access → Authentication: resolves identity (evidence: `src/lib/api-guard.ts`)
- Authentication → PostgreSQL database: reads identity records (evidence: `src/lib/auth.ts`)
- PostgreSQL database → Domain schema: configures ORM (evidence: `src/db/index.ts`)
- Domain schema → Event catalog and rules: uses rule types (evidence: `src/db/schema.ts`)
