# qianqiuzy/harei-frontend architecture

> Architecture diagram of the GitHub repository qianqiuzy/harei-frontend, 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/qianqiuzy/harei-frontend
- Repository: https://github.com/qianqiuzy/harei-frontend

## Overview

Harei Frontend is a Next.js site for public Harei pages and interactive features, with separate general-admin and music-admin areas. The main visitor flow spans home/status, message box, music catalog, downloads, and captain-gift content; admin workflows manage messages, images, captain-gift assets, and music metadata. The graph captures documented capabilities and source-index-supported relationships. Several route implementations are unsampled, so their internal calls are omitted rather than inferred.

Main entry points: [`app/box/page.tsx`](https://github.com/qianqiuzy/harei-frontend/blob/main/app/box/page.tsx) (Message box page), [`lib/music-admin/client.ts`](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music-admin/client.ts) (Music admin client), [`lib/auth/session.ts`](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/auth/session.ts) (Session and auth), [`lib/api.ts`](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/api.ts) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_visitor["Visitor experience"]
  node_home["Home and status<br/>[page.tsx]"]
  node_about["About page<br/>[page.tsx]"]
  node_downloads["Downloads<br/>[page.tsx]"]
  node_downloadproxy["Download proxy<br/>[route.ts]"]
  node_captain["Captain gifts<br/>[page.tsx]"]
  node_giftimage["Gift image route<br/>[route.ts]"]
end

subgraph group_box["Message box"]
  node_boxpage["Message box page<br/>[page.tsx]"]
  node_emojiui["Emoji editor and picker<br/>[BoxEmojiEditor.tsx]"]
  node_messageview["Message rendering<br/>[BoxMessage.tsx]"]
  node_emojiapi["Emoji API routes<br/>[route.ts]"]
  node_emojicatalog["Emoji catalog helpers<br/>[emojis.ts]"]
end

subgraph group_admin["Administration"]
  node_adminhome["Admin dashboard<br/>[page.tsx]"]
  node_adminmessages["Message moderation<br/>[page.tsx]"]
  node_audit["Admin audit<br/>[page.tsx]"]
  node_captainadmin["Gift administration<br/>[page.tsx]"]
  node_captainupload["Gift upload workflow"]
end

subgraph group_music["Music catalog"]
  node_musiccatalog["Music catalog UI<br/>[MusicCatalog.tsx]"]
  node_musicclient["Music API client<br/>[client.ts]"]
  node_musicschemas["Music data schemas<br/>[schemas.ts]"]
  node_musicadmin["Music management UI<br/>[page.tsx]"]
  node_performances["Performance manager"]
  node_musicadminclient["Music admin client<br/>[client.ts]"]
  node_adminschemas["Admin data schemas<br/>[schemas.ts]"]
end

subgraph group_shared["Shared services"]
  node_session["Session and auth<br/>[session.ts]"]
  node_apiclient["Browser API client<br/>[api.ts]"]
  node_serverapi["Server API base<br/>[server-api.ts]"]
end

node_visitor(("Visitor"))
node_backend{{"Harei backend"}}

node_visitor -->|"opens"| node_home
node_visitor -->|"uses"| node_boxpage
node_visitor -->|"browses"| node_musiccatalog
node_visitor -->|"opens"| node_downloads
node_visitor -->|"views"| node_captain
node_downloads -.->|"requests file"| node_downloadproxy
node_downloadproxy -->|"uses base"| node_serverapi
node_downloadproxy -->|"proxies download"| node_backend
node_captain -.->|"loads images"| node_giftimage
node_giftimage -->|"uses base"| node_serverapi
node_giftimage -->|"proxies image"| node_backend
node_boxpage -->|"renders"| node_emojiui
node_boxpage -->|"renders"| node_messageview
node_emojiui -->|"uses helpers"| node_emojicatalog
node_boxpage -->|"loads groups"| node_emojicatalog
node_emojiapi -->|"uses base"| node_serverapi
node_emojiapi -->|"proxies emoji"| node_backend
node_adminhome -.->|"authenticates"| node_session
node_adminmessages -->|"renders messages"| node_messageview
node_adminmessages -.->|"requires session"| node_session
node_audit -->|"renders messages"| node_messageview
node_captainadmin -.->|"uses workflow"| node_captainupload
node_musiccatalog -.->|"loads catalog"| node_musicclient
node_musicclient -->|"uses client"| node_apiclient
node_musicclient -->|"validates data"| node_musicschemas
node_musicadmin -.->|"calls management API"| node_musicadminclient
node_musicadmin -->|"uses session"| node_session
node_performances -->|"mutates records"| node_musicadminclient
node_musicadminclient -->|"uses client"| node_apiclient
node_musicadminclient -->|"validates responses"| node_adminschemas
node_adminschemas -->|"reuses schemas"| node_musicschemas
node_session -->|"calls auth API"| node_apiclient
node_apiclient -->|"sends browser requests"| node_backend
node_serverapi -->|"configures server proxy"| node_backend

click node_home "https://github.com/qianqiuzy/harei-frontend/blob/main/app/page.tsx"
click node_about "https://github.com/qianqiuzy/harei-frontend/blob/main/app/about/page.tsx"
click node_downloads "https://github.com/qianqiuzy/harei-frontend/blob/main/app/download/page.tsx"
click node_downloadproxy "https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/download-file/route.ts"
click node_captain "https://github.com/qianqiuzy/harei-frontend/blob/main/app/captaingift/page.tsx"
click node_giftimage "https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/captaingift-image/%5Bfilename%5D/route.ts"
click node_boxpage "https://github.com/qianqiuzy/harei-frontend/blob/main/app/box/page.tsx"
click node_emojiui "https://github.com/qianqiuzy/harei-frontend/blob/main/components/box/BoxEmojiEditor.tsx"
click node_messageview "https://github.com/qianqiuzy/harei-frontend/blob/main/components/box/BoxMessage.tsx"
click node_emojiapi "https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/emoji/route.ts"
click node_emojicatalog "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/box/emojis.ts"
click node_adminhome "https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/page.tsx"
click node_adminmessages "https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/message/page.tsx"
click node_audit "https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/audit/page.tsx"
click node_captainadmin "https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/captaingift/page.tsx"
click node_captainupload "https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/captaingift/use-captaingift-upload.ts"
click node_musiccatalog "https://github.com/qianqiuzy/harei-frontend/blob/main/app/music/_components/MusicCatalog.tsx"
click node_musicclient "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music/client.ts"
click node_musicschemas "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music/schemas.ts"
click node_musicadmin "https://github.com/qianqiuzy/harei-frontend/blob/main/app/music-admin/songs/page.tsx"
click node_performances "https://github.com/qianqiuzy/harei-frontend/blob/main/app/music-admin/_components/PerformanceManager.tsx"
click node_musicadminclient "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music-admin/client.ts"
click node_adminschemas "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music-admin/schemas.ts"
click node_session "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/auth/session.ts"
click node_apiclient "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/api.ts"
click node_serverapi "https://github.com/qianqiuzy/harei-frontend/blob/main/lib/server-api.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_about,node_downloads,node_downloadproxy,node_captain,node_giftimage toneBlue
class node_boxpage,node_emojiui,node_messageview,node_emojiapi,node_emojicatalog toneAmber
class node_adminhome,node_adminmessages,node_audit,node_captainadmin,node_captainupload toneMint
class node_musiccatalog,node_musicclient,node_musicschemas,node_musicadmin,node_performances,node_musicadminclient,node_adminschemas toneRose
class node_session,node_apiclient,node_serverapi,node_visitor,node_backend toneIndigo
```

## Components

### Visitor experience

- [Home and status](https://github.com/qianqiuzy/harei-frontend/blob/main/app/page.tsx): `app/page.tsx`
- [About page](https://github.com/qianqiuzy/harei-frontend/blob/main/app/about/page.tsx): `app/about/page.tsx`
- [Downloads](https://github.com/qianqiuzy/harei-frontend/blob/main/app/download/page.tsx): `app/download/page.tsx`
- [Download proxy](https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/download-file/route.ts): `app/api/download-file/route.ts`
- [Captain gifts](https://github.com/qianqiuzy/harei-frontend/blob/main/app/captaingift/page.tsx): `app/captaingift/page.tsx`
- [Gift image route](https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/captaingift-image/%5Bfilename%5D/route.ts): `app/api/captaingift-image/[filename]/route.ts`

### Message box

- [Message box page](https://github.com/qianqiuzy/harei-frontend/blob/main/app/box/page.tsx): `app/box/page.tsx`
- [Emoji editor and picker](https://github.com/qianqiuzy/harei-frontend/blob/main/components/box/BoxEmojiEditor.tsx): `components/box/BoxEmojiEditor.tsx`
- [Message rendering](https://github.com/qianqiuzy/harei-frontend/blob/main/components/box/BoxMessage.tsx): `components/box/BoxMessage.tsx`
- [Emoji API routes](https://github.com/qianqiuzy/harei-frontend/blob/main/app/api/emoji/route.ts): `app/api/emoji/route.ts`
- [Emoji catalog helpers](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/box/emojis.ts): `lib/box/emojis.ts`

### Administration

- [Admin dashboard](https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/page.tsx): `app/admin/page.tsx`
- [Message moderation](https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/message/page.tsx): `app/admin/message/page.tsx`
- [Admin audit](https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/audit/page.tsx): `app/admin/audit/page.tsx`
- [Gift administration](https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/captaingift/page.tsx): `app/admin/captaingift/page.tsx`
- [Gift upload workflow](https://github.com/qianqiuzy/harei-frontend/blob/main/app/admin/captaingift/use-captaingift-upload.ts): `app/admin/captaingift/use-captaingift-upload.ts`

### Music catalog

- [Music catalog UI](https://github.com/qianqiuzy/harei-frontend/blob/main/app/music/_components/MusicCatalog.tsx): `app/music/_components/MusicCatalog.tsx`
- [Music API client](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music/client.ts): `lib/music/client.ts`
- [Music data schemas](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music/schemas.ts): `lib/music/schemas.ts`
- [Music management UI](https://github.com/qianqiuzy/harei-frontend/blob/main/app/music-admin/songs/page.tsx): `app/music-admin/songs/page.tsx`
- [Performance manager](https://github.com/qianqiuzy/harei-frontend/blob/main/app/music-admin/_components/PerformanceManager.tsx): `app/music-admin/_components/PerformanceManager.tsx`
- [Music admin client](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music-admin/client.ts): `lib/music-admin/client.ts`
- [Admin data schemas](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/music-admin/schemas.ts): `lib/music-admin/schemas.ts`

### Shared services

- [Session and auth](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/auth/session.ts): `lib/auth/session.ts`
- [Browser API client](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/api.ts): `lib/api.ts`
- [Server API base](https://github.com/qianqiuzy/harei-frontend/blob/main/lib/server-api.ts): `lib/server-api.ts`

### Other components

- **Visitor**
- **Harei backend**

## Connections

- Visitor → Home and status: opens (evidence: `README.md`)
- Visitor → Message box page: uses (evidence: `README.md`)
- Visitor → Music catalog UI: browses (evidence: `README.md`)
- Visitor → Downloads: opens (evidence: `README.md`)
- Visitor → Captain gifts: views (evidence: `README.md`)
- Downloads → Download proxy: requests file
- Download proxy → Server API base: uses base (evidence: `app/api/download-file/route.ts`)
- Download proxy → Harei backend: proxies download (evidence: `app/api/download-file/route.ts`)
- Captain gifts → Gift image route: loads images
- Gift image route → Server API base: uses base (evidence: `app/api/captaingift-image/[filename]/route.ts`)
- Gift image route → Harei backend: proxies image (evidence: `app/api/captaingift-image/[filename]/route.ts`)
- Message box page → Emoji editor and picker: renders (evidence: `app/box/page.tsx`)
- Message box page → Message rendering: renders
- Emoji editor and picker → Emoji catalog helpers: uses helpers (evidence: `components/box/BoxEmojiEditor.tsx`)
- Message box page → Emoji catalog helpers: loads groups (evidence: `app/box/page.tsx`)
- Emoji API routes → Server API base: uses base (evidence: `app/api/emoji/route.ts`)
- Emoji API routes → Harei backend: proxies emoji (evidence: `app/api/emoji/route.ts`)
- Admin dashboard → Session and auth: authenticates
- Message moderation → Message rendering: renders messages (evidence: `app/admin/message/page.tsx`)
- Message moderation → Session and auth: requires session
- Admin audit → Message rendering: renders messages (evidence: `app/admin/audit/page.tsx`)
- Gift administration → Gift upload workflow: uses workflow
- Music catalog UI → Music API client: loads catalog
- Music API client → Browser API client: uses client (evidence: `lib/music/client.ts`)
- Music API client → Music data schemas: validates data (evidence: `lib/music/client.ts`)
- Music management UI → Music admin client: calls management API (evidence: `app/music-admin/songs/page.tsx`)
- Music management UI → Session and auth: uses session (evidence: `app/music-admin/songs/page.tsx`)
- Performance manager → Music admin client: mutates records (evidence: `app/music-admin/_components/PerformanceManager.tsx`)
- Music admin client → Browser API client: uses client (evidence: `lib/music-admin/client.ts`)
- Music admin client → Admin data schemas: validates responses (evidence: `lib/music-admin/client.ts`)
- Admin data schemas → Music data schemas: reuses schemas (evidence: `lib/music-admin/schemas.ts`)
- Session and auth → Browser API client: calls auth API (evidence: `lib/auth/session.ts`)
- Browser API client → Harei backend: sends browser requests (evidence: `README.md`)
- Server API base → Harei backend: configures server proxy (evidence: `README.md`)
