# 0x1kaan/pualim-app architecture

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

- Interactive diagram: https://gitdiagram.com/0x1kaan/pualim-app
- Repository: https://github.com/0x1kaan/pualim-app

## Overview

Pualım is a QR-based digital loyalty platform for Turkish cafés, designed to let customers use a loyalty card without installing an app. The customer workflow is phone verification by SMS, access to a café’s digital card, and viewing stamps, rewards, and visit history; the card UI also exposes a stamp-request flow. Café owners have onboarding and dashboard areas for café setup, customers, campaigns, analytics, and settings. The sampled sources confirm OTP and café/campaign/customer API behavior; dashboard-to-API wiring and several card actions were not sampled, so those relationships are not asserted.

Main entry points: [`src/lib/supabase/admin.ts`](https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/admin.ts) (Admin client), [`src/components/card/LoyaltyCardClient.tsx`](https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/LoyaltyCardClient.tsx) (Card experience), [`src/lib/supabase/server.ts`](https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/server.ts) (Server client), [`src/app/(dashboard)/dashboard/DashboardClient.tsx`](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/dashboard/DashboardClient.tsx) (Owner dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer loyalty"]
  node_qr_card["QR loyalty card<br/>[page.tsx]"]
  node_card_client["Card experience"]
  node_stamp_grid["Stamp grid<br/>[StampGrid.tsx]"]
  node_rewards_list["Rewards list<br/>[RewardsList.tsx]"]
  node_visit_history["Visit history<br/>[VisitHistory.tsx]"]
end

subgraph group_owner["Café management"]
  node_onboarding["Café onboarding<br/>[page.tsx]"]
  node_dashboard["Owner dashboard"]
  node_customer_mgmt["Customer management"]
  node_campaign_mgmt["Campaign management"]
  node_analytics["Analytics"]
  node_settings["Café settings<br/>[SettingsClient.tsx]"]
end

subgraph group_backend["Application backend"]
  node_otp_send["Send OTP<br/>[route.ts]"]
  node_otp_verify["Verify OTP<br/>[route.ts]"]
  node_cafe_api["Café API<br/>[route.ts]"]
  node_campaign_api["Campaign API<br/>[route.ts]"]
  node_customers_api["Customers API<br/>[route.ts]"]
  node_analytics_api["Analytics API<br/>[route.ts]"]
  node_stamp_request["Stamp request API<br/>[route.ts]"]
  node_stamp_approve["Stamp approval API<br/>[route.ts]"]
  node_card_customer_api["Card customer API<br/>[route.ts]"]
  node_card_rewards_api["Card rewards API<br/>[route.ts]"]
  node_card_history_api["Card history API<br/>[route.ts]"]
  node_redeem_api["Reward redemption API<br/>[route.ts]"]
end

subgraph group_platform["Platform services"]
  node_supabase_server["Server client<br/>[server.ts]"]
  node_supabase_admin["Admin client<br/>[admin.ts]"]
  node_database[("Supabase data<br/>[database.ts]")]
  node_sms_sender["SMS sender<br/>[sms.ts]"]
end

node_customer_actor(("Café customer"))
node_owner_actor(("Café owner"))
node_sms_provider["SMS provider"]

node_customer_actor -.->|"opens"| node_qr_card
node_qr_card -.->|"renders"| node_card_client
node_card_client -->|"requests code"| node_otp_send
node_card_client -->|"verifies code"| node_otp_verify
node_card_client -->|"loads customer"| node_card_customer_api
node_card_client -->|"renders"| node_stamp_grid
node_card_client -->|"renders"| node_rewards_list
node_card_client -->|"renders"| node_visit_history
node_card_client -.->|"requests stamp"| node_stamp_request
node_owner_actor -.->|"sets up café"| node_onboarding
node_owner_actor -.->|"manages café"| node_dashboard
node_dashboard -.->|"opens"| node_customer_mgmt
node_dashboard -.->|"opens"| node_campaign_mgmt
node_dashboard -.->|"opens"| node_analytics
node_dashboard -.->|"opens"| node_settings
node_otp_send -->|"reads and writes"| node_supabase_admin
node_otp_send -->|"sends message"| node_sms_sender
node_sms_sender -.->|"delivers SMS"| node_sms_provider
node_otp_verify -->|"reads and writes"| node_supabase_admin
node_cafe_api -->|"authenticates and reads"| node_supabase_server
node_cafe_api -->|"creates café"| node_supabase_admin
node_campaign_api -->|"reads and writes"| node_supabase_server
node_customers_api -->|"reads customers"| node_supabase_server
node_analytics_api -->|"queries summary"| node_supabase_server
node_card_customer_api -->|"reads customer"| node_supabase_admin
node_card_rewards_api -->|"reads rewards"| node_supabase_admin
node_card_history_api -->|"reads history"| node_supabase_admin
node_stamp_request -->|"records request"| node_supabase_admin
node_stamp_approve -->|"authenticates"| node_supabase_server
node_stamp_approve -->|"approves stamp"| node_supabase_admin
node_redeem_api -->|"redeems reward"| node_supabase_admin
node_supabase_server -->|"types queries"| node_database
node_supabase_admin -->|"types queries"| node_database

click node_qr_card "https://github.com/0x1kaan/pualim-app/blob/master/src/app/card/%5Bslug%5D/page.tsx"
click node_card_client "https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/LoyaltyCardClient.tsx"
click node_stamp_grid "https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/StampGrid.tsx"
click node_rewards_list "https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/RewardsList.tsx"
click node_visit_history "https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/VisitHistory.tsx"
click node_onboarding "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/onboarding/page.tsx"
click node_dashboard "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/dashboard/DashboardClient.tsx"
click node_customer_mgmt "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/customers/CustomersClient.tsx"
click node_campaign_mgmt "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/campaigns/CampaignsClient.tsx"
click node_analytics "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/analytics/AnalyticsClient.tsx"
click node_settings "https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/settings/SettingsClient.tsx"
click node_otp_send "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/auth/send-otp/route.ts"
click node_otp_verify "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/auth/verify-otp/route.ts"
click node_cafe_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/cafe/route.ts"
click node_campaign_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/campaigns/route.ts"
click node_customers_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/customers/route.ts"
click node_analytics_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/analytics/summary/route.ts"
click node_stamp_request "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/stamps/request/route.ts"
click node_stamp_approve "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/stamps/approve/route.ts"
click node_card_customer_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/%5Bslug%5D/customer/route.ts"
click node_card_rewards_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/rewards/route.ts"
click node_card_history_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/history/route.ts"
click node_redeem_api "https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/rewards/redeem/route.ts"
click node_supabase_server "https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/server.ts"
click node_supabase_admin "https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/admin.ts"
click node_database "https://github.com/0x1kaan/pualim-app/blob/master/src/types/database.ts"
click node_sms_sender "https://github.com/0x1kaan/pualim-app/blob/master/src/lib/notifications/sms.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_qr_card,node_card_client,node_stamp_grid,node_rewards_list,node_visit_history toneBlue
class node_onboarding,node_dashboard,node_customer_mgmt,node_campaign_mgmt,node_analytics,node_settings toneAmber
class node_otp_send,node_otp_verify,node_cafe_api,node_campaign_api,node_customers_api,node_analytics_api,node_stamp_request,node_stamp_approve,node_card_customer_api,node_card_rewards_api,node_card_history_api,node_redeem_api toneMint
class node_supabase_server,node_supabase_admin,node_database,node_sms_sender toneRose
class node_customer_actor,node_owner_actor,node_sms_provider toneIndigo
```

## Components

### Customer loyalty

- [QR loyalty card](https://github.com/0x1kaan/pualim-app/blob/master/src/app/card/%5Bslug%5D/page.tsx): `src/app/card/[slug]/page.tsx`
- [Card experience](https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/LoyaltyCardClient.tsx): `src/components/card/LoyaltyCardClient.tsx`
- [Stamp grid](https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/StampGrid.tsx): `src/components/card/StampGrid.tsx`
- [Rewards list](https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/RewardsList.tsx): `src/components/card/RewardsList.tsx`
- [Visit history](https://github.com/0x1kaan/pualim-app/blob/master/src/components/card/VisitHistory.tsx): `src/components/card/VisitHistory.tsx`

### Café management

- [Café onboarding](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/onboarding/page.tsx): `src/app/(dashboard)/onboarding/page.tsx`
- [Owner dashboard](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/dashboard/DashboardClient.tsx): `src/app/(dashboard)/dashboard/DashboardClient.tsx`
- [Customer management](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/customers/CustomersClient.tsx): `src/app/(dashboard)/customers/CustomersClient.tsx`
- [Campaign management](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/campaigns/CampaignsClient.tsx): `src/app/(dashboard)/campaigns/CampaignsClient.tsx`
- [Analytics](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/analytics/AnalyticsClient.tsx): `src/app/(dashboard)/analytics/AnalyticsClient.tsx`
- [Café settings](https://github.com/0x1kaan/pualim-app/blob/master/src/app/(dashboard)/settings/SettingsClient.tsx): `src/app/(dashboard)/settings/SettingsClient.tsx`

### Application backend

- [Send OTP](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/auth/send-otp/route.ts): `src/app/api/auth/send-otp/route.ts`
- [Verify OTP](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/auth/verify-otp/route.ts): `src/app/api/auth/verify-otp/route.ts`
- [Café API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/cafe/route.ts): `src/app/api/cafe/route.ts`
- [Campaign API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/campaigns/route.ts): `src/app/api/campaigns/route.ts`
- [Customers API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/customers/route.ts): `src/app/api/customers/route.ts`
- [Analytics API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/analytics/summary/route.ts): `src/app/api/analytics/summary/route.ts`
- [Stamp request API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/stamps/request/route.ts): `src/app/api/stamps/request/route.ts`
- [Stamp approval API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/stamps/approve/route.ts): `src/app/api/stamps/approve/route.ts`
- [Card customer API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/%5Bslug%5D/customer/route.ts): `src/app/api/card/[slug]/customer/route.ts`
- [Card rewards API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/rewards/route.ts): `src/app/api/card/rewards/route.ts`
- [Card history API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/card/history/route.ts): `src/app/api/card/history/route.ts`
- [Reward redemption API](https://github.com/0x1kaan/pualim-app/blob/master/src/app/api/rewards/redeem/route.ts): `src/app/api/rewards/redeem/route.ts`

### Platform services

- [Server client](https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Admin client](https://github.com/0x1kaan/pualim-app/blob/master/src/lib/supabase/admin.ts): `src/lib/supabase/admin.ts`
- [Supabase data](https://github.com/0x1kaan/pualim-app/blob/master/src/types/database.ts): `src/types/database.ts`
- [SMS sender](https://github.com/0x1kaan/pualim-app/blob/master/src/lib/notifications/sms.ts): `src/lib/notifications/sms.ts`

### Other components

- **Café customer**
- **Café owner**
- **SMS provider**

## Connections

- Café customer → QR loyalty card: opens
- QR loyalty card → Card experience: renders
- Card experience → Send OTP: requests code (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Verify OTP: verifies code (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Card customer API: loads customer (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Stamp grid: renders (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Rewards list: renders (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Visit history: renders (evidence: `src/components/card/LoyaltyCardClient.tsx`)
- Card experience → Stamp request API: requests stamp
- Café owner → Café onboarding: sets up café
- Café owner → Owner dashboard: manages café
- Owner dashboard → Customer management: opens
- Owner dashboard → Campaign management: opens
- Owner dashboard → Analytics: opens
- Owner dashboard → Café settings: opens
- Send OTP → Admin client: reads and writes (evidence: `src/app/api/auth/send-otp/route.ts`)
- Send OTP → SMS sender: sends message (evidence: `src/app/api/auth/send-otp/route.ts`)
- SMS sender → SMS provider: delivers SMS
- Verify OTP → Admin client: reads and writes (evidence: `src/app/api/auth/verify-otp/route.ts`)
- Café API → Server client: authenticates and reads (evidence: `src/app/api/cafe/route.ts`)
- Café API → Admin client: creates café (evidence: `src/app/api/cafe/route.ts`)
- Campaign API → Server client: reads and writes (evidence: `src/app/api/campaigns/route.ts`)
- Customers API → Server client: reads customers (evidence: `src/app/api/customers/route.ts`)
- Analytics API → Server client: queries summary (evidence: `src/app/api/analytics/summary/route.ts`)
- Card customer API → Admin client: reads customer
- Card rewards API → Admin client: reads rewards (evidence: `src/app/api/card/rewards/route.ts`)
- Card history API → Admin client: reads history (evidence: `src/app/api/card/history/route.ts`)
- Stamp request API → Admin client: records request (evidence: `src/app/api/stamps/request/route.ts`)
- Stamp approval API → Server client: authenticates (evidence: `src/app/api/stamps/approve/route.ts`)
- Stamp approval API → Admin client: approves stamp (evidence: `src/app/api/stamps/approve/route.ts`)
- Reward redemption API → Admin client: redeems reward (evidence: `src/app/api/rewards/redeem/route.ts`)
- Server client → Supabase data: types queries (evidence: `src/lib/supabase/server.ts`)
- Admin client → Supabase data: types queries (evidence: `src/lib/supabase/admin.ts`)
