# gyre-cyanyu/penghucalculator2 architecture

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

- Interactive diagram: https://gitdiagram.com/gyre-cyanyu/penghucalculator2
- Repository: https://github.com/gyre-cyanyu/penghucalculator2

## Overview

PenghuCalculator2 is a WeChat mini-program for managing Penghu scorekeeping rooms. Players create or join a room, take seats or spectate, record game actions, and see synchronized scores; settling a room archives its result for later history. The client pages invoke cloud functions and watch live room documents, while cloud functions operate on the rooms, histories, users, and notices collections. The main interaction paths are excerpted; several feature subsystems are represented from README and indexed filenames, so their internal call links are omitted where source evidence is unavailable.

Main entry points: [`cloudfunctions`](https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions) (Room and notice queries), [`miniprogram/pages/room/room.ts`](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/room/room.ts) (Live scoring), [`miniprogram/pages/information/information.ts`](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/information/information.ts) (Room details), [`miniprogram/pages/home/home.ts`](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/home/home.ts) (Home and joining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mini-program client"]
  node_home["Home and joining<br/>[home.ts]"]
  node_create["Create room<br/>[create.ts]"]
  node_format["Time formatting<br/>[format.ts]"]
  node_storage["Image cache<br/>[storage.ts]"]
  node_app["App identity<br/>[app.ts]"]
end

subgraph group_room["Room and scoring"]
  node_roompage["Live scoring<br/>[room.ts]"]
  node_info["Room details<br/>[information.ts]"]
end

subgraph group_account["User and history"]
  node_profile["Profile<br/>[profile.ts]"]
  node_historypage["History view<br/>[history.ts]"]
  node_history["History list<br/>[history.ts]"]
end

subgraph group_backend["Cloud operations"]
  node_createfn["Room creation<br/>[index.js]"]
  node_joinfn["Room membership<br/>[index.js]"]
  node_seatfn["Seat selection<br/>[index.js]"]
  node_actionfn["Score actions<br/>[index.js]"]
  node_undo["Undo actions<br/>[index.js]"]
  node_transfer["Transfer scores<br/>[index.js]"]
  node_settle["Room settlement<br/>[index.js]"]
  node_stateops["Room state updates"]
  node_queries["Room and notice queries"]
  node_userops["User data operations"]
  node_cleanup["Room cleanup<br/>[index.js]"]
end

subgraph group_data["Cloud data"]
  node_rooms[("Rooms collection")]
  node_histories[("Histories collection")]
  node_users[("Users collection")]
  node_notices[("Notices collection")]
  node_cloudstorage[("Cloud file storage")]
end

node_player(("Player"))

node_player -->|"opens"| node_home
node_player -->|"creates"| node_create
node_home -->|"joins room"| node_joinfn
node_create -.->|"creates room"| node_createfn
node_roompage -->|"selects seat"| node_seatfn
node_info -->|"selects seat"| node_seatfn
node_roompage -->|"watches updates"| node_rooms
node_info -->|"watches updates"| node_rooms
node_roompage -.->|"records action"| node_actionfn
node_roompage -.->|"requests undo"| node_undo
node_roompage -->|"transfers scores"| node_transfer
node_info -->|"updates room state"| node_stateops
node_info -->|"settles room"| node_settle
node_home -.->|"loads notices"| node_queries
node_home -.->|"loads joined rooms"| node_queries
node_app -->|"loads current user"| node_userops
node_profile -->|"updates profile"| node_userops
node_profile -->|"uploads avatar"| node_cloudstorage
node_historypage -->|"loads records"| node_history
node_history -->|"fetches histories"| node_queries
node_history -->|"fetches members"| node_userops
node_historypage -->|"formats dates"| node_format
node_historypage -->|"caches avatars"| node_storage
node_app -->|"caches avatar"| node_storage
node_createfn -.->|"creates document"| node_rooms
node_joinfn -.->|"updates members"| node_rooms
node_seatfn -->|"updates seats"| node_rooms
node_actionfn -->|"updates scores"| node_rooms
node_undo -->|"revises actions"| node_rooms
node_transfer -.->|"updates scores"| node_rooms
node_settle -.->|"reads room"| node_rooms
node_settle -.->|"archives result"| node_histories
node_stateops -.->|"updates state"| node_rooms
node_queries -.->|"queries rooms"| node_rooms
node_queries -.->|"queries history"| node_histories
node_queries -.->|"queries notices"| node_notices
node_userops -.->|"reads and writes"| node_users
node_cleanup -.->|"cleans stale rooms"| node_rooms
node_storage -->|"downloads files"| node_cloudstorage

click node_home "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/home/home.ts"
click node_create "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/create/create.ts"
click node_roompage "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/room/room.ts"
click node_info "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/information/information.ts"
click node_format "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/utils/format.ts"
click node_storage "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/utils/storage.ts"
click node_app "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/app.ts"
click node_profile "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/profile/profile.ts"
click node_historypage "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/history/history.ts"
click node_createfn "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_createRoomData/index.js"
click node_joinfn "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_updateMemberList/index.js"
click node_seatfn "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_updateNextPlayerTuple/index.js"
click node_actionfn "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_takeOperation/index.js"
click node_undo "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_undoAction/index.js"
click node_transfer "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_transferScores/index.js"
click node_settle "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_settleRoom/index.js"
click node_stateops "https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions"
click node_queries "https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions"
click node_userops "https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions"
click node_cleanup "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_clearRoomData/index.js"
click node_history "https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/history/history.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_home,node_create,node_format,node_storage,node_app toneBlue
class node_roompage,node_info toneAmber
class node_profile,node_historypage,node_history toneMint
class node_createfn,node_joinfn,node_seatfn,node_actionfn,node_undo,node_transfer,node_settle,node_stateops,node_queries,node_userops,node_cleanup toneRose
class node_rooms,node_histories,node_users,node_notices,node_cloudstorage,node_player toneIndigo
```

## Components

### Mini-program client

- [Home and joining](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/home/home.ts): `miniprogram/pages/home/home.ts`
- [Create room](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/create/create.ts): `miniprogram/pages/create/create.ts`
- [Time formatting](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/utils/format.ts): `miniprogram/utils/format.ts`
- [Image cache](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/utils/storage.ts): `miniprogram/utils/storage.ts`
- [App identity](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/app.ts): `miniprogram/app.ts`

### Room and scoring

- [Live scoring](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/room/room.ts): `miniprogram/pages/room/room.ts`
- [Room details](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/information/information.ts): `miniprogram/pages/information/information.ts`

### User and history

- [Profile](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/profile/profile.ts): `miniprogram/pages/profile/profile.ts`
- [History view](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/history/history.ts): `miniprogram/pages/history/history.ts`
- [History list](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/miniprogram/pages/history/history.ts): `miniprogram/pages/history/history.ts`

### Cloud operations

- [Room creation](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_createRoomData/index.js): `cloudfunctions/P2_createRoomData/index.js`
- [Room membership](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_updateMemberList/index.js): `cloudfunctions/P2_updateMemberList/index.js`
- [Seat selection](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_updateNextPlayerTuple/index.js): `cloudfunctions/P2_updateNextPlayerTuple/index.js`
- [Score actions](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_takeOperation/index.js): `cloudfunctions/P2_takeOperation/index.js`
- [Undo actions](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_undoAction/index.js): `cloudfunctions/P2_undoAction/index.js`
- [Transfer scores](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_transferScores/index.js): `cloudfunctions/P2_transferScores/index.js`
- [Room settlement](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_settleRoom/index.js): `cloudfunctions/P2_settleRoom/index.js`
- [Room state updates](https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions): `cloudfunctions`
- [Room and notice queries](https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions): `cloudfunctions`
- [User data operations](https://github.com/gyre-cyanyu/penghucalculator2/tree/main/cloudfunctions): `cloudfunctions`
- [Room cleanup](https://github.com/gyre-cyanyu/penghucalculator2/blob/main/cloudfunctions/P2_clearRoomData/index.js): `cloudfunctions/P2_clearRoomData/index.js`

### Cloud data

- **Rooms collection**
- **Histories collection**
- **Users collection**
- **Notices collection**
- **Cloud file storage**

### Other components

- **Player**

## Connections

- Player → Home and joining: opens
- Player → Create room: creates
- Home and joining → Room membership: joins room (evidence: `miniprogram/pages/home/home.ts`)
- Create room → Room creation: creates room
- Live scoring → Seat selection: selects seat (evidence: `miniprogram/pages/room/room.ts`)
- Room details → Seat selection: selects seat (evidence: `miniprogram/pages/information/information.ts`)
- Live scoring → Rooms collection: watches updates (evidence: `miniprogram/pages/room/room.ts`)
- Room details → Rooms collection: watches updates (evidence: `miniprogram/pages/information/information.ts`)
- Live scoring → Score actions: records action
- Live scoring → Undo actions: requests undo
- Live scoring → Transfer scores: transfers scores (evidence: `miniprogram/pages/room/room.ts`)
- Room details → Room state updates: updates room state (evidence: `miniprogram/pages/information/information.ts`)
- Room details → Room settlement: settles room (evidence: `miniprogram/pages/information/information.ts`)
- Home and joining → Room and notice queries: loads notices
- Home and joining → Room and notice queries: loads joined rooms
- App identity → User data operations: loads current user (evidence: `miniprogram/app.ts`)
- Profile → User data operations: updates profile (evidence: `miniprogram/pages/profile/profile.ts`)
- Profile → Cloud file storage: uploads avatar (evidence: `miniprogram/pages/profile/profile.ts`)
- History view → History list: loads records (evidence: `miniprogram/pages/history/history.ts`)
- History list → Room and notice queries: fetches histories (evidence: `miniprogram/pages/history/history.ts`)
- History list → User data operations: fetches members (evidence: `miniprogram/pages/history/history.ts`)
- History view → Time formatting: formats dates (evidence: `miniprogram/pages/history/history.ts`)
- History view → Image cache: caches avatars (evidence: `miniprogram/pages/history/history.ts`)
- App identity → Image cache: caches avatar (evidence: `miniprogram/app.ts`)
- Room creation → Rooms collection: creates document
- Room membership → Rooms collection: updates members
- Seat selection → Rooms collection: updates seats (evidence: `cloudfunctions/P2_updateNextPlayerTuple/index.js`)
- Score actions → Rooms collection: updates scores (evidence: `cloudfunctions/P2_takeOperation/index.js`)
- Undo actions → Rooms collection: revises actions (evidence: `cloudfunctions/P2_undoAction/index.js`)
- Transfer scores → Rooms collection: updates scores
- Room settlement → Rooms collection: reads room
- Room settlement → Histories collection: archives result
- Room state updates → Rooms collection: updates state
- Room and notice queries → Rooms collection: queries rooms
- Room and notice queries → Histories collection: queries history
- Room and notice queries → Notices collection: queries notices
- User data operations → Users collection: reads and writes
- Room cleanup → Rooms collection: cleans stale rooms
- Image cache → Cloud file storage: downloads files (evidence: `miniprogram/utils/storage.ts`)
