# m-3-blue/phonkhub architecture

> Architecture diagram of the GitHub repository m-3-blue/phonkhub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-3-blue/phonkhub
- Repository: https://github.com/m-3-blue/phonkhub

## Overview

PhonkHub is a community site for browsing music tracks and participating in discussions, with accounts, profiles, follows, reactions, and uploads. Its principal user flow is browsing a track and interacting through comments or votes; the repository also exposes forum, notification, and moderation capabilities. The sampled API handlers directly access Turso, and uploads also use Vercel Blob. The HTML files and several API handlers were not excerpted, so frontend-to-endpoint wiring and some subsystem relationships remain unverified.

Main entry points: [`track.html`](https://github.com/m-3-blue/phonkhub/blob/main/track.html) (Track page), [`profile.html`](https://github.com/m-3-blue/phonkhub/blob/main/profile.html) (Profile page), [`api/upload.js`](https://github.com/m-3-blue/phonkhub/blob/main/api/upload.js) (Image upload), [`index.html`](https://github.com/m-3-blue/phonkhub/blob/main/index.html) (Site pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_site["Site pages<br/>[index.html]"]
  node_track_view["Track page<br/>[track.html]"]
  node_profile_view["Profile page<br/>[profile.html]"]
  node_forum_views["Forum pages<br/>[forums.html]"]
  node_login_view["Login and signup<br/>[login.html]"]
end

subgraph group_identity["Accounts and profiles"]
  node_auth["Authentication<br/>[auth.js]"]
  node_profile["Profile management<br/>[profile.js]"]
  node_users["User activity<br/>[users.js]"]
  node_follow["Follow users<br/>[follow.js]"]
  node_upload["Image upload<br/>[upload.js]"]
end

subgraph group_music["Music community"]
  node_home["Home feed<br/>[home.js]"]
  node_tracks["Track catalog<br/>[tracks.js]"]
  node_track_page_api["Track details<br/>[track-page.js]"]
  node_comments["Track comments<br/>[comments.js]"]
  node_votes["Track votes<br/>[votes.js]"]
end

subgraph group_forums["Forums and engagement"]
  node_forums["Forum browsing<br/>[forums.js]"]
  node_forum_post["Forum posts<br/>[forum-post.js]"]
  node_forum_vote["Forum votes<br/>[forum-vote.js]"]
  node_react["Emoji reactions<br/>[react.js]"]
  node_notifications["Notifications<br/>[notifications.js]"]
  node_lockdown["Lockdown status<br/>[lockdown-status.js]"]
end

node_visitor(("Visitor"))
node_database[("Turso database")]
node_blob[("Vercel Blob")]

node_visitor -.->|"browses"| node_site
node_visitor -.->|"opens"| node_track_view
node_visitor -.->|"views"| node_profile_view
node_visitor -.->|"visits"| node_forum_views
node_visitor -.->|"signs in"| node_login_view
node_track_view -.->|"requests details"| node_track_page_api
node_track_view -.->|"requests comments"| node_comments
node_track_view -.->|"requests votes"| node_votes
node_profile_view -.->|"requests profile"| node_profile
node_profile_view -.->|"requests activity"| node_users
node_login_view -.->|"submits credentials"| node_auth
node_forum_views -.->|"requests threads"| node_forums
node_site -.->|"requests feed"| node_home
node_auth -->|"reads and writes"| node_database
node_comments -->|"reads and writes"| node_database
node_forum_post -->|"reads and writes"| node_database
node_forums -->|"reads"| node_database
node_profile -->|"reads and writes"| node_database
node_users -->|"reads"| node_database
node_follow -->|"reads and writes"| node_database
node_upload -->|"reads and writes"| node_database
node_upload -->|"uploads image"| node_blob
node_react -->|"reads and writes"| node_database
node_votes -->|"reads and writes"| node_database
node_forum_vote -->|"reads and writes"| node_database

click node_site "https://github.com/m-3-blue/phonkhub/blob/main/index.html"
click node_track_view "https://github.com/m-3-blue/phonkhub/blob/main/track.html"
click node_profile_view "https://github.com/m-3-blue/phonkhub/blob/main/profile.html"
click node_forum_views "https://github.com/m-3-blue/phonkhub/blob/main/forums.html"
click node_login_view "https://github.com/m-3-blue/phonkhub/blob/main/login.html"
click node_auth "https://github.com/m-3-blue/phonkhub/blob/main/api/auth.js"
click node_profile "https://github.com/m-3-blue/phonkhub/blob/main/api/profile.js"
click node_users "https://github.com/m-3-blue/phonkhub/blob/main/api/users.js"
click node_follow "https://github.com/m-3-blue/phonkhub/blob/main/api/follow.js"
click node_upload "https://github.com/m-3-blue/phonkhub/blob/main/api/upload.js"
click node_home "https://github.com/m-3-blue/phonkhub/blob/main/api/home.js"
click node_tracks "https://github.com/m-3-blue/phonkhub/blob/main/api/tracks.js"
click node_track_page_api "https://github.com/m-3-blue/phonkhub/blob/main/api/track-page.js"
click node_comments "https://github.com/m-3-blue/phonkhub/blob/main/api/comments.js"
click node_votes "https://github.com/m-3-blue/phonkhub/blob/main/api/votes.js"
click node_forums "https://github.com/m-3-blue/phonkhub/blob/main/api/forums.js"
click node_forum_post "https://github.com/m-3-blue/phonkhub/blob/main/api/forum-post.js"
click node_forum_vote "https://github.com/m-3-blue/phonkhub/blob/main/api/forum-vote.js"
click node_react "https://github.com/m-3-blue/phonkhub/blob/main/api/react.js"
click node_notifications "https://github.com/m-3-blue/phonkhub/blob/main/api/notifications.js"
click node_lockdown "https://github.com/m-3-blue/phonkhub/blob/main/api/lockdown-status.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_site,node_track_view,node_profile_view,node_forum_views,node_login_view toneBlue
class node_auth,node_profile,node_users,node_follow,node_upload,node_database,node_blob toneAmber
class node_home,node_tracks,node_track_page_api,node_comments,node_votes toneMint
class node_forums,node_forum_post,node_forum_vote,node_react,node_notifications,node_lockdown toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Site pages](https://github.com/m-3-blue/phonkhub/blob/main/index.html): `index.html`
- [Track page](https://github.com/m-3-blue/phonkhub/blob/main/track.html): `track.html`
- [Profile page](https://github.com/m-3-blue/phonkhub/blob/main/profile.html): `profile.html`
- [Forum pages](https://github.com/m-3-blue/phonkhub/blob/main/forums.html): `forums.html`
- [Login and signup](https://github.com/m-3-blue/phonkhub/blob/main/login.html): `login.html`

### Accounts and profiles

- [Authentication](https://github.com/m-3-blue/phonkhub/blob/main/api/auth.js): `api/auth.js`
- [Profile management](https://github.com/m-3-blue/phonkhub/blob/main/api/profile.js): `api/profile.js`
- [User activity](https://github.com/m-3-blue/phonkhub/blob/main/api/users.js): `api/users.js`
- [Follow users](https://github.com/m-3-blue/phonkhub/blob/main/api/follow.js): `api/follow.js`
- [Image upload](https://github.com/m-3-blue/phonkhub/blob/main/api/upload.js): `api/upload.js`

### Music community

- [Home feed](https://github.com/m-3-blue/phonkhub/blob/main/api/home.js): `api/home.js`
- [Track catalog](https://github.com/m-3-blue/phonkhub/blob/main/api/tracks.js): `api/tracks.js`
- [Track details](https://github.com/m-3-blue/phonkhub/blob/main/api/track-page.js): `api/track-page.js`
- [Track comments](https://github.com/m-3-blue/phonkhub/blob/main/api/comments.js): `api/comments.js`
- [Track votes](https://github.com/m-3-blue/phonkhub/blob/main/api/votes.js): `api/votes.js`

### Forums and engagement

- [Forum browsing](https://github.com/m-3-blue/phonkhub/blob/main/api/forums.js): `api/forums.js`
- [Forum posts](https://github.com/m-3-blue/phonkhub/blob/main/api/forum-post.js): `api/forum-post.js`
- [Forum votes](https://github.com/m-3-blue/phonkhub/blob/main/api/forum-vote.js): `api/forum-vote.js`
- [Emoji reactions](https://github.com/m-3-blue/phonkhub/blob/main/api/react.js): `api/react.js`
- [Notifications](https://github.com/m-3-blue/phonkhub/blob/main/api/notifications.js): `api/notifications.js`
- [Lockdown status](https://github.com/m-3-blue/phonkhub/blob/main/api/lockdown-status.js): `api/lockdown-status.js`

### Other components

- **Visitor**
- **Turso database**
- **Vercel Blob**

## Connections

- Visitor → Site pages: browses
- Visitor → Track page: opens
- Visitor → Profile page: views
- Visitor → Forum pages: visits
- Visitor → Login and signup: signs in
- Track page → Track details: requests details
- Track page → Track comments: requests comments
- Track page → Track votes: requests votes
- Profile page → Profile management: requests profile
- Profile page → User activity: requests activity
- Login and signup → Authentication: submits credentials
- Forum pages → Forum browsing: requests threads
- Site pages → Home feed: requests feed
- Authentication → Turso database: reads and writes (evidence: `api/auth.js`)
- Track comments → Turso database: reads and writes (evidence: `api/comments.js`)
- Forum posts → Turso database: reads and writes (evidence: `api/forum-post.js`)
- Forum browsing → Turso database: reads (evidence: `api/forums.js`)
- Profile management → Turso database: reads and writes (evidence: `api/profile.js`)
- User activity → Turso database: reads (evidence: `api/users.js`)
- Follow users → Turso database: reads and writes (evidence: `api/follow.js`)
- Image upload → Turso database: reads and writes (evidence: `api/upload.js`)
- Image upload → Vercel Blob: uploads image (evidence: `api/upload.js`)
- Emoji reactions → Turso database: reads and writes (evidence: `api/react.js`)
- Track votes → Turso database: reads and writes (evidence: `api/votes.js`)
- Forum votes → Turso database: reads and writes (evidence: `api/forum-vote.js`)
