# nurasss/cashback-one architecture

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

- Interactive diagram: https://gitdiagram.com/nurasss/cashback-one
- Repository: https://github.com/nurasss/cashback-one

## Overview

POSCENTER Loyalty mirrors POSCENTER ONE balances and operations in a cloud API; it does not calculate or redeem loyalty value itself. The main workflow is Windows agent synchronization into the cloud, followed by customer authentication and wallet/app reads, with admin management alongside. The README also identifies Stage 0 discovery, notifications, wallet passes, and POS QR/redemption APIs as product capabilities. Edges are limited to relationships supported by excerpts or README; unsampled subsystem internals are represented at their owning directories.

Main entry points: [`backend/app/main.py`](https://github.com/nurasss/cashback-one/blob/main/backend/app/main.py) (FastAPI Entry), [`mobile/src/api/app.ts`](https://github.com/nurasss/cashback-one/blob/main/mobile/src/api/app.ts) (Mobile API), [`agent/src/poscenter_loyalty_agent/runtime.py`](https://github.com/nurasss/cashback-one/blob/main/agent/src/poscenter_loyalty_agent/runtime.py) (Sync Runtime), [`backend/app/services/wallet_service.py`](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/wallet_service.py) (Wallet Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["ONE Sync Agent"]
  node_agent_runtime["Sync Runtime<br/>[runtime.py]"]
  node_agent_state[("Sync State<br/>[state_store.py]")]
  node_agent_stage0["Stage 0 Discovery"]
end

subgraph group_cloud["Cloud API"]
  node_api["FastAPI Entry<br/>[main.py]"]
  node_agent_sync["Agent Sync API<br/>[agent_sync.py]"]
  node_agent_pos["POS APIs<br/>[agent_pos.py]"]
  node_pos["POS Services<br/>[pos.py]"]
  node_auth["Customer Auth"]
  node_wallet["Wallet Service<br/>[wallet_service.py]"]
  node_loyalty["Loyalty Mirror<br/>[loyalty.py]"]
  node_content["App Content<br/>[content_service.py]"]
  node_admin_services["Admin Operations<br/>[admin_queries.py]"]
  node_media["Media Storage<br/>[media_storage.py]"]
  node_entities[("Cloud Data<br/>[entities.py]")]
  node_notifications["Notifications"]
  node_webhooks["Wappi Webhook<br/>[webhooks.py]"]
end

subgraph group_customer["Customer App"]
  node_customer_app["Mobile Screens<br/>[index.tsx]"]
  node_mobile_auth["Mobile Session<br/>[provider.tsx]"]
  node_mobile_api["Mobile API<br/>[app.ts]"]
  node_mobile_cache[("App Cache<br/>[appCache.ts]")]
  node_mobile_login["Login Screen<br/>[login.tsx]"]
end

subgraph group_admin["Admin Console"]
  node_admin_routes["Admin Routes<br/>[AdminRoutes.tsx]"]
  node_admin_pages["Admin Pages<br/>[BusinessesPage.tsx]"]
  node_admin_api["Admin API Client<br/>[client.ts]"]
end

subgraph group_integrations["External Services"]
  node_wappi["Wappi"]
  node_sms["SMS Provider"]
  node_ftps["FTPS Hosting"]
  node_push["Push Service"]
end

node_one["POSCENTER ONE"]

node_one -->|"read-only data"| node_agent_runtime
node_agent_runtime -->|"stores sync state"| node_agent_state
node_agent_runtime -->|"pushes sync"| node_agent_sync
node_agent_stage0 -.->|"profiles schema"| node_one
node_api -->|"routes requests"| node_agent_sync
node_api -->|"routes requests"| node_agent_pos
node_api -->|"routes requests"| node_pos
node_api -->|"routes requests"| node_webhooks
node_agent_sync -.->|"mirrors records"| node_entities
node_agent_pos -.->|"dispatches POS calls"| node_pos
node_api -.->|"serves customer login"| node_auth
node_auth -->|"sends OTP"| node_sms
node_api -.->|"serves wallet requests"| node_wallet
node_wallet -->|"reads loyalty data"| node_loyalty
node_wallet -->|"reads mirror"| node_entities
node_api -.->|"serves app content"| node_content
node_api -.->|"serves admin requests"| node_admin_services
node_media -->|"uploads media"| node_ftps
node_webhooks -->|"receives events"| node_wappi
node_api -->|"starts scheduler"| node_notifications
node_notifications -.->|"sends notifications"| node_push
node_customer_app -.->|"requests app data"| node_mobile_api
node_mobile_login -->|"starts session"| node_mobile_auth
node_mobile_auth -->|"provides session API"| node_mobile_api
node_mobile_api -->|"caches content"| node_mobile_cache
node_mobile_api -.->|"calls cloud API"| node_api
node_admin_routes -->|"routes to pages"| node_admin_pages
node_admin_pages -.->|"requests admin data"| node_admin_api
node_admin_api -.->|"calls cloud API"| node_api

click node_agent_runtime "https://github.com/nurasss/cashback-one/blob/main/agent/src/poscenter_loyalty_agent/runtime.py"
click node_agent_state "https://github.com/nurasss/cashback-one/blob/main/agent/src/poscenter_loyalty_agent/state_store.py"
click node_agent_stage0 "https://github.com/nurasss/cashback-one/tree/main/agent/src/poscenter_loyalty_agent/stage0"
click node_api "https://github.com/nurasss/cashback-one/blob/main/backend/app/main.py"
click node_agent_sync "https://github.com/nurasss/cashback-one/blob/main/backend/app/api/agent_sync.py"
click node_agent_pos "https://github.com/nurasss/cashback-one/blob/main/backend/app/api/agent_pos.py"
click node_pos "https://github.com/nurasss/cashback-one/blob/main/backend/app/api/pos.py"
click node_auth "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/sms_auth_service.py"
click node_wallet "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/wallet_service.py"
click node_loyalty "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/loyalty.py"
click node_content "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/content_service.py"
click node_admin_services "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/admin_queries.py"
click node_media "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/media_storage.py"
click node_entities "https://github.com/nurasss/cashback-one/blob/main/backend/app/models/entities.py"
click node_notifications "https://github.com/nurasss/cashback-one/blob/main/backend/app/services/notification_scheduler.py"
click node_webhooks "https://github.com/nurasss/cashback-one/blob/main/backend/app/api/webhooks.py"
click node_customer_app "https://github.com/nurasss/cashback-one/blob/main/mobile/app/(app)/(tabs)/index.tsx"
click node_mobile_auth "https://github.com/nurasss/cashback-one/blob/main/mobile/src/auth/provider.tsx"
click node_mobile_api "https://github.com/nurasss/cashback-one/blob/main/mobile/src/api/app.ts"
click node_mobile_cache "https://github.com/nurasss/cashback-one/blob/main/mobile/src/storage/appCache.ts"
click node_mobile_login "https://github.com/nurasss/cashback-one/blob/main/mobile/app/login.tsx"
click node_admin_routes "https://github.com/nurasss/cashback-one/blob/main/admin/src/layout/AdminRoutes.tsx"
click node_admin_pages "https://github.com/nurasss/cashback-one/blob/main/admin/src/pages/BusinessesPage.tsx"
click node_admin_api "https://github.com/nurasss/cashback-one/blob/main/admin/src/api/client.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_agent_runtime,node_agent_state,node_agent_stage0 toneBlue
class node_api,node_agent_sync,node_agent_pos,node_pos,node_auth,node_wallet,node_loyalty,node_content,node_admin_services,node_media,node_entities,node_notifications,node_webhooks toneAmber
class node_customer_app,node_mobile_auth,node_mobile_api,node_mobile_cache,node_mobile_login toneMint
class node_admin_routes,node_admin_pages,node_admin_api toneRose
class node_wappi,node_sms,node_ftps,node_push,node_one toneIndigo
```

## Components

### ONE Sync Agent

- [Sync Runtime](https://github.com/nurasss/cashback-one/blob/main/agent/src/poscenter_loyalty_agent/runtime.py): `agent/src/poscenter_loyalty_agent/runtime.py`
- [Sync State](https://github.com/nurasss/cashback-one/blob/main/agent/src/poscenter_loyalty_agent/state_store.py): `agent/src/poscenter_loyalty_agent/state_store.py`
- [Stage 0 Discovery](https://github.com/nurasss/cashback-one/tree/main/agent/src/poscenter_loyalty_agent/stage0): `agent/src/poscenter_loyalty_agent/stage0`

### Cloud API

- [FastAPI Entry](https://github.com/nurasss/cashback-one/blob/main/backend/app/main.py): `backend/app/main.py`
- [Agent Sync API](https://github.com/nurasss/cashback-one/blob/main/backend/app/api/agent_sync.py): `backend/app/api/agent_sync.py`
- [POS APIs](https://github.com/nurasss/cashback-one/blob/main/backend/app/api/agent_pos.py): `backend/app/api/agent_pos.py`
- [POS Services](https://github.com/nurasss/cashback-one/blob/main/backend/app/api/pos.py): `backend/app/api/pos.py`
- [Customer Auth](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/sms_auth_service.py): `backend/app/services/sms_auth_service.py`
- [Wallet Service](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/wallet_service.py): `backend/app/services/wallet_service.py`
- [Loyalty Mirror](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/loyalty.py): `backend/app/services/loyalty.py`
- [App Content](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/content_service.py): `backend/app/services/content_service.py`
- [Admin Operations](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/admin_queries.py): `backend/app/services/admin_queries.py`
- [Media Storage](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/media_storage.py): `backend/app/services/media_storage.py`
- [Cloud Data](https://github.com/nurasss/cashback-one/blob/main/backend/app/models/entities.py): `backend/app/models/entities.py`
- [Notifications](https://github.com/nurasss/cashback-one/blob/main/backend/app/services/notification_scheduler.py): `backend/app/services/notification_scheduler.py`
- [Wappi Webhook](https://github.com/nurasss/cashback-one/blob/main/backend/app/api/webhooks.py): `backend/app/api/webhooks.py`

### Customer App

- [Mobile Screens](https://github.com/nurasss/cashback-one/blob/main/mobile/app/(app)/(tabs)/index.tsx): `mobile/app/(app)/(tabs)/index.tsx`
- [Mobile Session](https://github.com/nurasss/cashback-one/blob/main/mobile/src/auth/provider.tsx): `mobile/src/auth/provider.tsx`
- [Mobile API](https://github.com/nurasss/cashback-one/blob/main/mobile/src/api/app.ts): `mobile/src/api/app.ts`
- [App Cache](https://github.com/nurasss/cashback-one/blob/main/mobile/src/storage/appCache.ts): `mobile/src/storage/appCache.ts`
- [Login Screen](https://github.com/nurasss/cashback-one/blob/main/mobile/app/login.tsx): `mobile/app/login.tsx`

### Admin Console

- [Admin Routes](https://github.com/nurasss/cashback-one/blob/main/admin/src/layout/AdminRoutes.tsx): `admin/src/layout/AdminRoutes.tsx`
- [Admin Pages](https://github.com/nurasss/cashback-one/blob/main/admin/src/pages/BusinessesPage.tsx): `admin/src/pages/BusinessesPage.tsx`
- [Admin API Client](https://github.com/nurasss/cashback-one/blob/main/admin/src/api/client.ts): `admin/src/api/client.ts`

### External Services

- **Wappi**
- **SMS Provider**
- **FTPS Hosting**
- **Push Service**

### Other components

- **POSCENTER ONE**

## Connections

- POSCENTER ONE → Sync Runtime: read-only data
- Sync Runtime → Sync State: stores sync state (evidence: `agent/src/poscenter_loyalty_agent/runtime.py`)
- Sync Runtime → Agent Sync API: pushes sync
- Stage 0 Discovery → POSCENTER ONE: profiles schema
- FastAPI Entry → Agent Sync API: routes requests (evidence: `backend/app/main.py`)
- FastAPI Entry → POS APIs: routes requests (evidence: `backend/app/main.py`)
- FastAPI Entry → POS Services: routes requests (evidence: `backend/app/main.py`)
- FastAPI Entry → Wappi Webhook: routes requests (evidence: `backend/app/main.py`)
- Agent Sync API → Cloud Data: mirrors records
- POS APIs → POS Services: dispatches POS calls
- FastAPI Entry → Customer Auth: serves customer login
- Customer Auth → SMS Provider: sends OTP (evidence: `backend/app/services/sms_auth_service.py`)
- FastAPI Entry → Wallet Service: serves wallet requests
- Wallet Service → Loyalty Mirror: reads loyalty data (evidence: `backend/app/services/wallet_service.py`)
- Wallet Service → Cloud Data: reads mirror (evidence: `backend/app/services/wallet_service.py`)
- FastAPI Entry → App Content: serves app content
- FastAPI Entry → Admin Operations: serves admin requests
- Media Storage → FTPS Hosting: uploads media (evidence: `backend/app/services/media_storage.py`)
- Wappi Webhook → Wappi: receives events (evidence: `backend/app/api/webhooks.py`)
- FastAPI Entry → Notifications: starts scheduler (evidence: `backend/app/main.py`)
- Notifications → Push Service: sends notifications
- Mobile Screens → Mobile API: requests app data
- Login Screen → Mobile Session: starts session (evidence: `mobile/app/login.tsx`)
- Mobile Session → Mobile API: provides session API (evidence: `mobile/src/auth/provider.tsx`)
- Mobile API → App Cache: caches content (evidence: `mobile/src/api/app.ts`)
- Mobile API → FastAPI Entry: calls cloud API
- Admin Routes → Admin Pages: routes to pages (evidence: `admin/src/layout/AdminRoutes.tsx`)
- Admin Pages → Admin API Client: requests admin data
- Admin API Client → FastAPI Entry: calls cloud API