# haru-1293/festival-qr-pos architecture

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

- Interactive diagram: https://gitdiagram.com/haru-1293/festival-qr-pos
- Repository: https://github.com/haru-1293/festival-qr-pos

## Overview

festival-qr-pos is a festival QR-payment and POS system: customers register, receive wallet balance, and pay at shop checkout; reception staff charge and reconcile cash, while shop and system managers maintain operations. The React client fronts a Workers API backed by D1. The graph preserves the documented authentication, wallet, reception, catalog, discounts, sets, cards, checkout, refunds, and administration capabilities. Some client-to-API connections are shown as unverified because client call sites were not excerpted; route-to-service links are based on the source index.

Main entry points: [`src/worker/index.ts`](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/index.ts) (API gateway), [`src/client/lib/api.ts`](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/lib/api.ts) (HTTP client), [`src/client/App.tsx`](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/App.tsx) (Client application), [`src/worker/routes/pos.ts`](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/pos.ts) (POS and payment routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_clientapp["Client application<br/>[App.tsx]"]
  node_authpages["Login and account<br/>[AuthPages.tsx]"]
  node_posui["Shop checkout<br/>[Checkout.tsx]"]
  node_receptionui["Reception desk<br/>[ChargePanel.tsx]"]
  node_shopadminui["Shop management<br/>[ProductManager.tsx]"]
  node_adminui["System administration<br/>[AdminUsers.tsx]"]
  node_clientapi["HTTP client<br/>[api.ts]"]
end

subgraph group_api["Worker API"]
  node_gateway["API gateway<br/>[index.ts]"]
  node_authroutes["Authentication routes<br/>[auth.ts]"]
  node_catalogroutes["Catalog routes<br/>[catalog.ts]"]
  node_posroutes["POS and payment routes<br/>[pos.ts]"]
  node_receptionroutes["Reception routes<br/>[reception.ts]"]
  node_refundroutes["Refund routes<br/>[refunds.ts]"]
  node_adminroutes["Admin and shop routes<br/>[admin.ts]"]
  node_otherops["Other operations routes"]
end

subgraph group_domain["Commerce services"]
  node_catalog["Catalog and sets<br/>[catalog.ts]"]
  node_orders["Pricing and orders<br/>[order.ts]"]
  node_discounts["Discount rules<br/>[discounts.ts]"]
  node_cards["Physical cards<br/>[cards.ts]"]
  node_cash["Cash operations<br/>[cash.ts]"]
end

subgraph group_identity["Identity and operations"]
  node_authmiddleware["Session and access<br/>[auth.ts]"]
  node_sessions["Session handling<br/>[session.ts]"]
  node_crypto["Credential cryptography<br/>[crypto.ts]"]
  node_audit["Audit records<br/>[audit.ts]"]
  node_settings["Festival settings<br/>[settings.ts]"]
end

node_customer(("Customer"))
node_receptionist(("Reception staff"))
node_shopstaff(("Shop staff"))
node_admin(("System manager"))
node_d1[("D1 database")]

node_customer -.->|"registers or signs in"| node_authpages
node_customer -.->|"presents payment QR"| node_posui
node_receptionist -.->|"charges wallet"| node_receptionui
node_shopstaff -.->|"checks out sales"| node_posui
node_admin -.->|"manages system"| node_adminui
node_clientapp -.->|"hosts"| node_authpages
node_clientapp -.->|"hosts"| node_posui
node_clientapp -.->|"hosts"| node_receptionui
node_clientapp -.->|"hosts"| node_shopadminui
node_clientapp -.->|"hosts"| node_adminui
node_authpages -.->|"requests API"| node_clientapi
node_posui -.->|"requests API"| node_clientapi
node_receptionui -.->|"requests API"| node_clientapi
node_shopadminui -.->|"requests API"| node_clientapi
node_adminui -.->|"requests API"| node_clientapi
node_clientapi -.->|"calls API"| node_gateway
node_gateway -->|"routes requests"| node_authroutes
node_gateway -->|"routes requests"| node_catalogroutes
node_gateway -->|"routes requests"| node_posroutes
node_gateway -->|"routes requests"| node_receptionroutes
node_gateway -->|"routes requests"| node_refundroutes
node_gateway -->|"routes requests"| node_adminroutes
node_gateway -->|"routes requests"| node_otherops
node_gateway -->|"loads sessions"| node_authmiddleware
node_authroutes -->|"creates sessions"| node_sessions
node_authroutes -->|"verifies credentials"| node_crypto
node_authroutes -->|"records events"| node_audit
node_authmiddleware -->|"uses cookie settings"| node_sessions
node_authmiddleware -->|"hashes session token"| node_crypto
node_catalogroutes -->|"builds catalog"| node_catalog
node_posroutes -->|"builds POS catalog"| node_catalog
node_posroutes -->|"quotes and settles"| node_orders
node_posroutes -->|"checks card"| node_cards
node_receptionroutes -->|"uses cash operations"| node_cash
node_receptionroutes -->|"uses card operations"| node_cards
node_refundroutes -->|"loads payment result"| node_orders
node_refundroutes -->|"uses catalog data"| node_catalog
node_posroutes -->|"records events"| node_audit
node_receptionroutes -->|"records events"| node_audit
node_catalog -.->|"reads catalog data"| node_d1
node_orders -.->|"reads and writes orders"| node_d1
node_cash -.->|"records cash"| node_d1
node_audit -->|"inserts audit logs"| node_d1
node_sessions -->|"builds session SQL"| node_d1
node_settings -.->|"stores settings"| node_d1

click node_clientapp "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/App.tsx"
click node_authpages "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/AuthPages.tsx"
click node_posui "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/pos/Checkout.tsx"
click node_receptionui "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/reception/ChargePanel.tsx"
click node_shopadminui "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/shop/ProductManager.tsx"
click node_adminui "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/admin/AdminUsers.tsx"
click node_clientapi "https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/lib/api.ts"
click node_gateway "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/index.ts"
click node_authroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/auth.ts"
click node_catalogroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/catalog.ts"
click node_posroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/pos.ts"
click node_receptionroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/reception.ts"
click node_refundroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/refunds.ts"
click node_adminroutes "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/admin.ts"
click node_otherops "https://github.com/haru-1293/festival-qr-pos/tree/main/src/worker/routes"
click node_catalog "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/catalog.ts"
click node_orders "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/order.ts"
click node_discounts "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/discounts.ts"
click node_cards "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/cards.ts"
click node_cash "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/cash.ts"
click node_authmiddleware "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/middleware/auth.ts"
click node_sessions "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/session.ts"
click node_crypto "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/crypto.ts"
click node_audit "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/audit.ts"
click node_settings "https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/settings.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_clientapp,node_authpages,node_posui,node_receptionui,node_shopadminui,node_adminui,node_clientapi toneBlue
class node_gateway,node_authroutes,node_catalogroutes,node_posroutes,node_receptionroutes,node_refundroutes,node_adminroutes,node_otherops,node_d1 toneAmber
class node_catalog,node_orders,node_discounts,node_cards,node_cash toneMint
class node_authmiddleware,node_sessions,node_crypto,node_audit,node_settings toneRose
class node_customer,node_receptionist,node_shopstaff,node_admin toneIndigo
```

## Components

### React client

- [Client application](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/App.tsx): `src/client/App.tsx`
- [Login and account](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/AuthPages.tsx): `src/client/pages/AuthPages.tsx`
- [Shop checkout](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/pos/Checkout.tsx): `src/client/pages/pos/Checkout.tsx`
- [Reception desk](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/reception/ChargePanel.tsx): `src/client/pages/reception/ChargePanel.tsx`
- [Shop management](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/shop/ProductManager.tsx): `src/client/pages/shop/ProductManager.tsx`
- [System administration](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/pages/admin/AdminUsers.tsx): `src/client/pages/admin/AdminUsers.tsx`
- [HTTP client](https://github.com/haru-1293/festival-qr-pos/blob/main/src/client/lib/api.ts): `src/client/lib/api.ts`

### Worker API

- [API gateway](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/index.ts): `src/worker/index.ts`
- [Authentication routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/auth.ts): `src/worker/routes/auth.ts`
- [Catalog routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/catalog.ts): `src/worker/routes/catalog.ts`
- [POS and payment routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/pos.ts): `src/worker/routes/pos.ts`
- [Reception routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/reception.ts): `src/worker/routes/reception.ts`
- [Refund routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/refunds.ts): `src/worker/routes/refunds.ts`
- [Admin and shop routes](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/routes/admin.ts): `src/worker/routes/admin.ts`
- [Other operations routes](https://github.com/haru-1293/festival-qr-pos/tree/main/src/worker/routes): `src/worker/routes`

### Commerce services

- [Catalog and sets](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/catalog.ts): `src/worker/lib/catalog.ts`
- [Pricing and orders](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/order.ts): `src/worker/lib/order.ts`
- [Discount rules](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/discounts.ts): `src/worker/lib/discounts.ts`
- [Physical cards](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/cards.ts): `src/worker/lib/cards.ts`
- [Cash operations](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/cash.ts): `src/worker/lib/cash.ts`

### Identity and operations

- [Session and access](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/middleware/auth.ts): `src/worker/middleware/auth.ts`
- [Session handling](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/session.ts): `src/worker/lib/session.ts`
- [Credential cryptography](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/crypto.ts): `src/worker/lib/crypto.ts`
- [Audit records](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/audit.ts): `src/worker/lib/audit.ts`
- [Festival settings](https://github.com/haru-1293/festival-qr-pos/blob/main/src/worker/lib/settings.ts): `src/worker/lib/settings.ts`

### Other components

- **Customer**
- **Reception staff**
- **Shop staff**
- **System manager**
- **D1 database**

## Connections

- Customer → Login and account: registers or signs in (evidence: `README.md`)
- Customer → Shop checkout: presents payment QR (evidence: `README.md`)
- Reception staff → Reception desk: charges wallet (evidence: `README.md`)
- Shop staff → Shop checkout: checks out sales (evidence: `README.md`)
- System manager → System administration: manages system (evidence: `README.md`)
- Client application → Login and account: hosts
- Client application → Shop checkout: hosts
- Client application → Reception desk: hosts
- Client application → Shop management: hosts
- Client application → System administration: hosts
- Login and account → HTTP client: requests API
- Shop checkout → HTTP client: requests API
- Reception desk → HTTP client: requests API
- Shop management → HTTP client: requests API
- System administration → HTTP client: requests API
- HTTP client → API gateway: calls API
- API gateway → Authentication routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Catalog routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → POS and payment routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Reception routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Refund routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Admin and shop routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Other operations routes: routes requests (evidence: `src/worker/index.ts`)
- API gateway → Session and access: loads sessions (evidence: `src/worker/index.ts`)
- Authentication routes → Session handling: creates sessions (evidence: `src/worker/routes/auth.ts`)
- Authentication routes → Credential cryptography: verifies credentials (evidence: `src/worker/routes/auth.ts`)
- Authentication routes → Audit records: records events (evidence: `src/worker/routes/auth.ts`)
- Session and access → Session handling: uses cookie settings (evidence: `src/worker/middleware/auth.ts`)
- Session and access → Credential cryptography: hashes session token (evidence: `src/worker/middleware/auth.ts`)
- Catalog routes → Catalog and sets: builds catalog (evidence: `src/worker/routes/catalog.ts`)
- POS and payment routes → Catalog and sets: builds POS catalog (evidence: `src/worker/routes/pos.ts`)
- POS and payment routes → Pricing and orders: quotes and settles (evidence: `src/worker/routes/pos.ts`)
- POS and payment routes → Physical cards: checks card (evidence: `src/worker/routes/pos.ts`)
- Reception routes → Cash operations: uses cash operations (evidence: `src/worker/routes/reception.ts`)
- Reception routes → Physical cards: uses card operations (evidence: `src/worker/routes/reception.ts`)
- Refund routes → Pricing and orders: loads payment result (evidence: `src/worker/routes/refunds.ts`)
- Refund routes → Catalog and sets: uses catalog data (evidence: `src/worker/routes/refunds.ts`)
- POS and payment routes → Audit records: records events (evidence: `src/worker/routes/pos.ts`)
- Reception routes → Audit records: records events (evidence: `src/worker/routes/reception.ts`)
- Catalog and sets → D1 database: reads catalog data
- Pricing and orders → D1 database: reads and writes orders
- Cash operations → D1 database: records cash
- Audit records → D1 database: inserts audit logs (evidence: `src/worker/lib/audit.ts`)
- Session handling → D1 database: builds session SQL (evidence: `src/worker/lib/session.ts`)
- Festival settings → D1 database: stores settings
