# wjiangh/donut_town architecture

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

- Interactive diagram: https://gitdiagram.com/wjiangh/donut_town
- Repository: https://github.com/wjiangh/donut_town

## Overview

Donut Town is a Slack-connected pixel-town app: teammates enter through Slack, appear as residents, explore and personalize the town, and use chat, home, and shop features. The main runtime divides between the browser town client and the Node server, which handles sign-in, API requests, and persistence. The README documents major capabilities whose detailed implementations were not sampled; those are represented at their supported module paths. Connections are limited to excerpted imports/calls and explicit README statements.

Main entry points: [`server.mjs`](https://github.com/wjiangh/donut_town/blob/main/server.mjs) (HTTP server), [`app.js`](https://github.com/wjiangh/donut_town/blob/main/app.js) (Town client), [`town-themes/service.mjs`](https://github.com/wjiangh/donut_town/blob/main/town-themes/service.mjs) (Theme service), [`chats/service.mjs`](https://github.com/wjiangh/donut_town/blob/main/chats/service.mjs) (Chat history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and server"]
  node_server["HTTP server<br/>[server.mjs]"]
  node_session["OAuth sessions<br/>[session.mjs]"]
  node_slackoidc["Slack sign-in<br/>[oidc.mjs]"]
end

subgraph group_town["Town experience"]
  node_townclient["Town client<br/>[app.js]"]
  node_presence["Live presence<br/>[presence.mjs]"]
  node_themesclient["Theme settings<br/>[client.mjs]"]
  node_themecontract["Theme contract<br/>[contract.mjs]"]
  node_themeservice["Theme service<br/>[service.mjs]"]
  node_themestore[("Theme storage<br/>[store.mjs]")]
end

subgraph group_identity["Residents and places"]
  node_characters["Character catalog<br/>[catalog.mjs]"]
  node_wardrobe["Wardrobe rendering<br/>[renderer.mjs]"]
  node_wardrobestore[("Wardrobe storage<br/>[store.mjs]")]
  node_pets["Pet companion<br/>[pets.mjs]"]
  node_house["Home and visits<br/>[house.mjs]"]
  node_luxury["Home luxury<br/>[luxury.mjs]"]
end

subgraph group_social["Social and economy"]
  node_chats["Chat history<br/>[service.mjs]"]
  node_chatstore[("Chat records<br/>[store.mjs]")]
  node_invitations["Donut invitations<br/>[invitations.mjs]"]
  node_shop["Shop experience<br/>[shop-room.mjs]"]
  node_shopstore[("Shop inventory<br/>[store.mjs]")]
  node_socialclient["Town social UI<br/>[social-client.mjs]"]
  node_socialstore[("Social records<br/>[store.mjs]")]
end

subgraph group_integrations["External services and storage"]
  node_slackapi["Slack API client<br/>[client.mjs]"]
  node_lottery["Lottery bridge<br/>[bridge.mjs]"]
end

node_teammate(("Slack teammate"))
node_slack{{"Slack platform"}}
node_browser(("Town browser"))
node_upstash[("Upstash Redis")]

node_teammate -->|"signs in"| node_slack
node_slack -->|"launches town"| node_server
node_server -->|"verifies state"| node_session
node_server -->|"exchanges code"| node_slackoidc
node_browser -->|"opens"| node_townclient
node_townclient -.->|"tracks presence"| node_presence
node_townclient -->|"mounts settings"| node_themesclient
node_themesclient -->|"validates theme"| node_themecontract
node_server -->|"routes theme API"| node_themeservice
node_themeservice -->|"checks permissions"| node_themecontract
node_themeservice -.->|"loads and saves"| node_themestore
node_townclient -->|"uses residents"| node_characters
node_townclient -->|"renders outfits"| node_wardrobe
node_server -->|"loads wardrobe"| node_wardrobestore
node_townclient -->|"shows pets"| node_pets
node_townclient -->|"opens homes"| node_house
node_house -->|"calculates luxury"| node_luxury
node_server -->|"routes chat actions"| node_chats
node_chats -.->|"reads and confirms"| node_chatstore
node_chats -->|"loads pair rounds"| node_invitations
node_server -->|"handles invitations"| node_invitations
node_townclient -->|"opens shop"| node_shop
node_server -->|"handles purchases"| node_shopstore
node_townclient -->|"mounts social UI"| node_socialclient
node_server -->|"routes social actions"| node_socialstore
node_socialstore -->|"reads and writes"| node_upstash
node_lottery -->|"reads active round"| node_invitations
node_lottery -->|"reads round records"| node_upstash
node_slackapi -->|"calls API"| node_slack
node_server -.->|"uses Slack API"| node_slackapi

click node_server "https://github.com/wjiangh/donut_town/blob/main/server.mjs"
click node_session "https://github.com/wjiangh/donut_town/blob/main/slack/session.mjs"
click node_slackoidc "https://github.com/wjiangh/donut_town/blob/main/slack/oidc.mjs"
click node_slackapi "https://github.com/wjiangh/donut_town/blob/main/slack/client.mjs"
click node_townclient "https://github.com/wjiangh/donut_town/blob/main/app.js"
click node_presence "https://github.com/wjiangh/donut_town/blob/main/realtime/presence.mjs"
click node_themesclient "https://github.com/wjiangh/donut_town/blob/main/town-themes/client.mjs"
click node_themecontract "https://github.com/wjiangh/donut_town/blob/main/town-themes/contract.mjs"
click node_themeservice "https://github.com/wjiangh/donut_town/blob/main/town-themes/service.mjs"
click node_themestore "https://github.com/wjiangh/donut_town/blob/main/town-themes/store.mjs"
click node_characters "https://github.com/wjiangh/donut_town/blob/main/characters/catalog.mjs"
click node_wardrobe "https://github.com/wjiangh/donut_town/blob/main/characters/wardrobe/renderer.mjs"
click node_wardrobestore "https://github.com/wjiangh/donut_town/blob/main/characters/wardrobe/store.mjs"
click node_pets "https://github.com/wjiangh/donut_town/blob/main/pets.mjs"
click node_house "https://github.com/wjiangh/donut_town/blob/main/house.mjs"
click node_luxury "https://github.com/wjiangh/donut_town/blob/main/house/luxury.mjs"
click node_chats "https://github.com/wjiangh/donut_town/blob/main/chats/service.mjs"
click node_chatstore "https://github.com/wjiangh/donut_town/blob/main/chats/store.mjs"
click node_invitations "https://github.com/wjiangh/donut_town/blob/main/slack/invitations.mjs"
click node_shop "https://github.com/wjiangh/donut_town/blob/main/shop-room.mjs"
click node_shopstore "https://github.com/wjiangh/donut_town/blob/main/shop/store.mjs"
click node_socialclient "https://github.com/wjiangh/donut_town/blob/main/social-client.mjs"
click node_socialstore "https://github.com/wjiangh/donut_town/blob/main/social/store.mjs"
click node_lottery "https://github.com/wjiangh/donut_town/blob/main/lottery/bridge.mjs"

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_server,node_session,node_slackoidc,node_browser toneBlue
class node_townclient,node_presence,node_themesclient,node_themecontract,node_themeservice,node_themestore,node_upstash toneAmber
class node_characters,node_wardrobe,node_wardrobestore,node_pets,node_house,node_luxury toneMint
class node_chats,node_chatstore,node_invitations,node_shop,node_shopstore,node_socialclient,node_socialstore toneRose
class node_slackapi,node_lottery,node_teammate,node_slack toneIndigo
```

## Components

### Access and server

- [HTTP server](https://github.com/wjiangh/donut_town/blob/main/server.mjs): `server.mjs`
- [OAuth sessions](https://github.com/wjiangh/donut_town/blob/main/slack/session.mjs): `slack/session.mjs`
- [Slack sign-in](https://github.com/wjiangh/donut_town/blob/main/slack/oidc.mjs): `slack/oidc.mjs`

### Town experience

- [Town client](https://github.com/wjiangh/donut_town/blob/main/app.js): `app.js`
- [Live presence](https://github.com/wjiangh/donut_town/blob/main/realtime/presence.mjs): `realtime/presence.mjs`
- [Theme settings](https://github.com/wjiangh/donut_town/blob/main/town-themes/client.mjs): `town-themes/client.mjs`
- [Theme contract](https://github.com/wjiangh/donut_town/blob/main/town-themes/contract.mjs): `town-themes/contract.mjs`
- [Theme service](https://github.com/wjiangh/donut_town/blob/main/town-themes/service.mjs): `town-themes/service.mjs`
- [Theme storage](https://github.com/wjiangh/donut_town/blob/main/town-themes/store.mjs): `town-themes/store.mjs`

### Residents and places

- [Character catalog](https://github.com/wjiangh/donut_town/blob/main/characters/catalog.mjs): `characters/catalog.mjs`
- [Wardrobe rendering](https://github.com/wjiangh/donut_town/blob/main/characters/wardrobe/renderer.mjs): `characters/wardrobe/renderer.mjs`
- [Wardrobe storage](https://github.com/wjiangh/donut_town/blob/main/characters/wardrobe/store.mjs): `characters/wardrobe/store.mjs`
- [Pet companion](https://github.com/wjiangh/donut_town/blob/main/pets.mjs): `pets.mjs`
- [Home and visits](https://github.com/wjiangh/donut_town/blob/main/house.mjs): `house.mjs`
- [Home luxury](https://github.com/wjiangh/donut_town/blob/main/house/luxury.mjs): `house/luxury.mjs`

### Social and economy

- [Chat history](https://github.com/wjiangh/donut_town/blob/main/chats/service.mjs): `chats/service.mjs`
- [Chat records](https://github.com/wjiangh/donut_town/blob/main/chats/store.mjs): `chats/store.mjs`
- [Donut invitations](https://github.com/wjiangh/donut_town/blob/main/slack/invitations.mjs): `slack/invitations.mjs`
- [Shop experience](https://github.com/wjiangh/donut_town/blob/main/shop-room.mjs): `shop-room.mjs`
- [Shop inventory](https://github.com/wjiangh/donut_town/blob/main/shop/store.mjs): `shop/store.mjs`
- [Town social UI](https://github.com/wjiangh/donut_town/blob/main/social-client.mjs): `social-client.mjs`
- [Social records](https://github.com/wjiangh/donut_town/blob/main/social/store.mjs): `social/store.mjs`

### External services and storage

- [Slack API client](https://github.com/wjiangh/donut_town/blob/main/slack/client.mjs): `slack/client.mjs`
- [Lottery bridge](https://github.com/wjiangh/donut_town/blob/main/lottery/bridge.mjs): `lottery/bridge.mjs`

### Other components

- **Slack teammate**
- **Slack platform**
- **Town browser**
- **Upstash Redis**

## Connections

- Slack teammate → Slack platform: signs in
- Slack platform → HTTP server: launches town
- HTTP server → OAuth sessions: verifies state (evidence: `server.mjs`)
- HTTP server → Slack sign-in: exchanges code (evidence: `server.mjs`)
- Town browser → Town client: opens
- Town client → Live presence: tracks presence
- Town client → Theme settings: mounts settings (evidence: `app.js`)
- Theme settings → Theme contract: validates theme (evidence: `town-themes/client.mjs`)
- HTTP server → Theme service: routes theme API (evidence: `server.mjs`)
- Theme service → Theme contract: checks permissions (evidence: `town-themes/service.mjs`)
- Theme service → Theme storage: loads and saves
- Town client → Character catalog: uses residents (evidence: `app.js`)
- Town client → Wardrobe rendering: renders outfits (evidence: `app.js`)
- HTTP server → Wardrobe storage: loads wardrobe (evidence: `server.mjs`)
- Town client → Pet companion: shows pets (evidence: `app.js`)
- Town client → Home and visits: opens homes (evidence: `app.js`)
- Home and visits → Home luxury: calculates luxury (evidence: `house.mjs`)
- HTTP server → Chat history: routes chat actions (evidence: `server.mjs`)
- Chat history → Chat records: reads and confirms
- Chat history → Donut invitations: loads pair rounds (evidence: `chats/service.mjs`)
- HTTP server → Donut invitations: handles invitations (evidence: `server.mjs`)
- Town client → Shop experience: opens shop (evidence: `app.js`)
- HTTP server → Shop inventory: handles purchases (evidence: `server.mjs`)
- Town client → Town social UI: mounts social UI (evidence: `app.js`)
- HTTP server → Social records: routes social actions (evidence: `server.mjs`)
- Social records → Upstash Redis: reads and writes (evidence: `social/store.mjs`)
- Lottery bridge → Donut invitations: reads active round (evidence: `lottery/bridge.mjs`)
- Lottery bridge → Upstash Redis: reads round records (evidence: `lottery/bridge.mjs`)
- Slack API client → Slack platform: calls API (evidence: `slack/client.mjs`)
- HTTP server → Slack API client: uses Slack API (evidence: `server.mjs`)
