# miusicbox/miusic architecture

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

- Interactive diagram: https://gitdiagram.com/miusicbox/miusic
- Repository: https://github.com/miusicbox/miusic

## Overview

MIUSIC BOX is a browser-based music catalog and sales application with customer ordering and an administrative interface. Customers browse songs and playlists, add items to a cart, receive discount and promotion pricing, and place or look up orders. Administrators manage catalog and pricing data, accounts, and order processing, including ZIP downloads. The tree and excerpts support the client-to-Worker-to-D1 architecture and selected storage flows; some page wiring and feature details are inferred only from filenames, so uncertain links are omitted.

Main entry points: [`worker/index.js`](https://github.com/miusicbox/miusic/blob/main/worker/index.js) (API and ZIP jobs), [`db-client.js`](https://github.com/miusicbox/miusic/blob/main/db-client.js) (Document API client), [`app-user.js`](https://github.com/miusicbox/miusic/blob/main/app-user.js) (Catalog and orders), [`storage-adapter.js`](https://github.com/miusicbox/miusic/blob/main/storage-adapter.js) (Upload adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer storefront"]
  node_storefront["Storefront page<br/>[index.html]"]
  node_customer_app["Catalog and orders<br/>[app-user.js]"]
  node_cart["Cart and checkout<br/>[app-cart.js]"]
  node_promotions["Discounts and promotions<br/>[app-promotion.js]"]
end

subgraph group_admin["Administration"]
  node_admin_page["Admin page<br/>[admin.html]"]
  node_admin_app["Catalog management<br/>[app-admin.js]"]
  node_order_admin["Order management<br/>[orders.js]"]
  node_admin_roles["Admin roles<br/>[admin-roles.js]"]
  node_auth_client["Authentication client<br/>[auth-client.js]"]
  node_storage_adapter["Upload adapter<br/>[storage-adapter.js]"]
end

subgraph group_backend["Worker services"]
  node_db_client["Document API client<br/>[db-client.js]"]
  node_worker["API and ZIP jobs<br/>[index.js]"]
  node_auth_helpers["Session and passwords<br/>[auth-helpers.js]"]
  node_db_helpers["Document operations<br/>[db-helpers.js]"]
  node_zip_format["Streaming ZIP format<br/>[zip-format.js]"]
end

subgraph group_data["Persistence and files"]
  node_d1[("Cloudflare D1")]
  node_bucket[("Object storage")]
end

node_customer_actor(("Customer"))
node_admin_actor(("Administrator"))
node_cloudinary["Cloudinary"]

node_customer_actor -->|"opens"| node_storefront
node_storefront -->|"loads"| node_customer_app
node_customer_app -->|"adds items"| node_cart
node_customer_app -->|"loads pricing"| node_promotions
node_cart -->|"gets pricing"| node_promotions
node_customer_app -->|"reads catalog"| node_db_client
node_cart -->|"reads and saves"| node_db_client
node_admin_actor -->|"opens"| node_admin_page
node_admin_page -->|"loads"| node_admin_app
node_admin_page -->|"loads"| node_order_admin
node_admin_app -->|"manages catalog"| node_db_client
node_admin_app -->|"uploads files"| node_storage_adapter
node_order_admin -->|"manages orders"| node_db_client
node_order_admin -->|"requests files"| node_storage_adapter
node_admin_roles -->|"accesses data"| node_db_client
node_auth_client -->|"calls auth API"| node_worker
node_db_client -->|"calls data API"| node_worker
node_worker -->|"uses sessions"| node_auth_helpers
node_worker -->|"uses document operations"| node_db_helpers
node_auth_helpers -->|"reads and writes sessions"| node_d1
node_db_helpers -->|"reads and writes documents"| node_d1
node_worker -->|"builds ZIP streams"| node_zip_format
node_worker -->|"reads and writes files"| node_bucket
node_storage_adapter -.->|"uploads"| node_cloudinary
node_storage_adapter -.->|"requests R2 upload"| node_worker

click node_storefront "https://github.com/miusicbox/miusic/blob/main/index.html"
click node_customer_app "https://github.com/miusicbox/miusic/blob/main/app-user.js"
click node_cart "https://github.com/miusicbox/miusic/blob/main/app-cart.js"
click node_promotions "https://github.com/miusicbox/miusic/blob/main/app-promotion.js"
click node_admin_page "https://github.com/miusicbox/miusic/blob/main/admin.html"
click node_admin_app "https://github.com/miusicbox/miusic/blob/main/app-admin.js"
click node_order_admin "https://github.com/miusicbox/miusic/blob/main/orders.js"
click node_admin_roles "https://github.com/miusicbox/miusic/blob/main/admin-roles.js"
click node_auth_client "https://github.com/miusicbox/miusic/blob/main/auth-client.js"
click node_storage_adapter "https://github.com/miusicbox/miusic/blob/main/storage-adapter.js"
click node_db_client "https://github.com/miusicbox/miusic/blob/main/db-client.js"
click node_worker "https://github.com/miusicbox/miusic/blob/main/worker/index.js"
click node_auth_helpers "https://github.com/miusicbox/miusic/blob/main/worker/auth-helpers.js"
click node_db_helpers "https://github.com/miusicbox/miusic/blob/main/worker/db-helpers.js"
click node_zip_format "https://github.com/miusicbox/miusic/blob/main/worker/zip-format.js"

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_storefront,node_customer_app,node_cart,node_promotions toneBlue
class node_admin_page,node_admin_app,node_order_admin,node_admin_roles,node_auth_client,node_storage_adapter toneAmber
class node_db_client,node_worker,node_auth_helpers,node_db_helpers,node_zip_format toneMint
class node_d1,node_bucket toneRose
class node_customer_actor,node_admin_actor,node_cloudinary toneIndigo
```

## Components

### Customer storefront

- [Storefront page](https://github.com/miusicbox/miusic/blob/main/index.html): `index.html`
- [Catalog and orders](https://github.com/miusicbox/miusic/blob/main/app-user.js): `app-user.js`
- [Cart and checkout](https://github.com/miusicbox/miusic/blob/main/app-cart.js): `app-cart.js`
- [Discounts and promotions](https://github.com/miusicbox/miusic/blob/main/app-promotion.js): `app-promotion.js`

### Administration

- [Admin page](https://github.com/miusicbox/miusic/blob/main/admin.html): `admin.html`
- [Catalog management](https://github.com/miusicbox/miusic/blob/main/app-admin.js): `app-admin.js`
- [Order management](https://github.com/miusicbox/miusic/blob/main/orders.js): `orders.js`
- [Admin roles](https://github.com/miusicbox/miusic/blob/main/admin-roles.js): `admin-roles.js`
- [Authentication client](https://github.com/miusicbox/miusic/blob/main/auth-client.js): `auth-client.js`
- [Upload adapter](https://github.com/miusicbox/miusic/blob/main/storage-adapter.js): `storage-adapter.js`

### Worker services

- [Document API client](https://github.com/miusicbox/miusic/blob/main/db-client.js): `db-client.js`
- [API and ZIP jobs](https://github.com/miusicbox/miusic/blob/main/worker/index.js): `worker/index.js`
- [Session and passwords](https://github.com/miusicbox/miusic/blob/main/worker/auth-helpers.js): `worker/auth-helpers.js`
- [Document operations](https://github.com/miusicbox/miusic/blob/main/worker/db-helpers.js): `worker/db-helpers.js`
- [Streaming ZIP format](https://github.com/miusicbox/miusic/blob/main/worker/zip-format.js): `worker/zip-format.js`

### Persistence and files

- **Cloudflare D1**
- **Object storage**

### Other components

- **Customer**
- **Administrator**
- **Cloudinary**

## Connections

- Customer → Storefront page: opens
- Storefront page → Catalog and orders: loads
- Catalog and orders → Cart and checkout: adds items
- Catalog and orders → Discounts and promotions: loads pricing
- Cart and checkout → Discounts and promotions: gets pricing
- Catalog and orders → Document API client: reads catalog
- Cart and checkout → Document API client: reads and saves
- Administrator → Admin page: opens
- Admin page → Catalog management: loads
- Admin page → Order management: loads
- Catalog management → Document API client: manages catalog
- Catalog management → Upload adapter: uploads files
- Order management → Document API client: manages orders
- Order management → Upload adapter: requests files
- Admin roles → Document API client: accesses data
- Authentication client → API and ZIP jobs: calls auth API
- Document API client → API and ZIP jobs: calls data API
- API and ZIP jobs → Session and passwords: uses sessions
- API and ZIP jobs → Document operations: uses document operations
- Session and passwords → Cloudflare D1: reads and writes sessions
- Document operations → Cloudflare D1: reads and writes documents
- API and ZIP jobs → Streaming ZIP format: builds ZIP streams
- API and ZIP jobs → Object storage: reads and writes files
- Upload adapter → Cloudinary: uploads
- Upload adapter → API and ZIP jobs: requests R2 upload