# gillandghaz/gramofon-web architecture

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

- Interactive diagram: https://gitdiagram.com/gillandghaz/gramofon-web
- Repository: https://github.com/gillandghaz/gramofon-web

## Overview

Gramofon is a browser-based personal audio/video library and player, with private playlists and an admin-managed shared Explore catalog. The main user journey is sign-in, upload media directly to Cloudinary through a server-authorized signed-upload flow, register metadata in Firestore, then manage and play the collection; admins also curate shared media and manage users and settings. The graph combines documented capabilities with sampled route and library evidence; the large app page and several feature modules were not inspected, so their internal call paths are not inferred.

Main entry points: [`src/lib/server-auth.js`](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/server-auth.js) (Server authorization), [`src/lib/firebase-admin.js`](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/firebase-admin.js) (Firebase Admin access), [`src/lib/cloudinary-admin.js`](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/cloudinary-admin.js) (Cloudinary administration), [`src/app/app/page.js`](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/app/page.js) (Player and library UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_landing["Landing and auth pages<br/>[page.js]"]
  node_login["Login and registration<br/>[page.js]"]
  node_mainapp["Player and library UI<br/>[page.js]"]
  node_dashboard["Account dashboard<br/>[page.js]"]
  node_adminui["Admin controls<br/>[AdminTab.js]"]
end

subgraph group_identity["Identity and accounts"]
  node_authcontext["Client auth state<br/>[auth-context.js]"]
  node_profile["User profiles<br/>[profile.js]"]
  node_authapi["Session and auth routes"]
  node_useradmin["User administration<br/>[route.js]"]
  node_photoapi["Profile photo routes"]
end

subgraph group_library["Media and catalogs"]
  node_privateupload["Private media routes"]
  node_exploreroutes["Explore catalog routes"]
end

subgraph group_services["Backend and services"]
  node_serverauth["Server authorization<br/>[server-auth.js]"]
  node_adminfirebase["Firebase Admin access<br/>[firebase-admin.js]"]
  node_clientfirebase["Firebase client SDK<br/>[firebase.js]"]
  node_cloudadmin["Cloudinary administration"]
  node_cloudupload["Client media upload"]
  node_firestore[("Firestore metadata")]
  node_firebaseauth["Firebase Authentication"]
  node_cloudinary[("Cloudinary media store")]
end

node_browser(("Browser user"))

node_browser -->|"opens"| node_landing
node_browser -->|"signs in"| node_login
node_browser -->|"uses player"| node_mainapp
node_browser -->|"manages account"| node_dashboard
node_browser -->|"administers"| node_adminui
node_login -->|"authenticates with"| node_firebaseauth
node_authcontext -->|"uses SDK"| node_clientfirebase
node_authcontext -->|"ensures profile"| node_profile
node_authcontext -->|"listens to profile"| node_firestore
node_mainapp -->|"uses SDK"| node_clientfirebase
node_mainapp -->|"requests upload authorization"| node_privateupload
node_privateupload -->|"checks user"| node_serverauth
node_privateupload -->|"reads and writes metadata"| node_adminfirebase
node_privateupload -->|"signs and verifies assets"| node_cloudadmin
node_adminfirebase -->|"accesses"| node_firestore
node_clientfirebase -->|"reads and writes"| node_firestore
node_clientfirebase -->|"uses"| node_firebaseauth
node_browser -->|"uploads signed media"| node_cloudinary
node_cloudadmin -->|"signs and manages assets"| node_cloudinary
node_browser -->|"streams media"| node_cloudinary
node_mainapp -->|"loads shared catalog"| node_exploreroutes
node_exploreroutes -->|"checks admin"| node_serverauth
node_exploreroutes -->|"stores catalog metadata"| node_adminfirebase
node_exploreroutes -->|"verifies and manages assets"| node_cloudadmin
node_adminui -->|"removes users"| node_useradmin
node_useradmin -->|"deletes account data"| node_adminfirebase
node_useradmin -->|"cleans profile image"| node_cloudadmin
node_authapi -->|"verifies sessions"| node_serverauth
node_serverauth -->|"verifies tokens and profiles"| node_adminfirebase
node_dashboard -->|"updates profile photo"| node_photoapi
node_photoapi -->|"checks user"| node_serverauth
node_photoapi -->|"verifies image"| node_cloudadmin

click node_landing "https://github.com/gillandghaz/gramofon-web/blob/main/src/app/page.js"
click node_login "https://github.com/gillandghaz/gramofon-web/blob/main/src/app/login/page.js"
click node_mainapp "https://github.com/gillandghaz/gramofon-web/blob/main/src/app/app/page.js"
click node_dashboard "https://github.com/gillandghaz/gramofon-web/blob/main/src/app/dashboard/page.js"
click node_adminui "https://github.com/gillandghaz/gramofon-web/blob/main/src/components/tabs/AdminTab.js"
click node_authcontext "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/auth-context.js"
click node_profile "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/profile.js"
click node_authapi "https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/auth"
click node_useradmin "https://github.com/gillandghaz/gramofon-web/blob/main/src/app/api/admin/delete-user/route.js"
click node_privateupload "https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/media"
click node_exploreroutes "https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/explore"
click node_photoapi "https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/profile/photo"
click node_serverauth "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/server-auth.js"
click node_adminfirebase "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/firebase-admin.js"
click node_clientfirebase "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/firebase.js"
click node_cloudadmin "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/cloudinary-admin.js"
click node_cloudupload "https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/cloudinary-upload.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_landing,node_login,node_mainapp,node_dashboard,node_adminui,node_browser toneBlue
class node_authcontext,node_profile,node_authapi,node_useradmin,node_photoapi toneAmber
class node_privateupload,node_exploreroutes toneMint
class node_serverauth,node_adminfirebase,node_clientfirebase,node_cloudadmin,node_cloudupload,node_firestore,node_firebaseauth,node_cloudinary toneRose
```

## Components

### Web experience

- [Landing and auth pages](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/page.js): `src/app/page.js`
- [Login and registration](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/login/page.js): `src/app/login/page.js`
- [Player and library UI](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/app/page.js): `src/app/app/page.js`
- [Account dashboard](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/dashboard/page.js): `src/app/dashboard/page.js`
- [Admin controls](https://github.com/gillandghaz/gramofon-web/blob/main/src/components/tabs/AdminTab.js): `src/components/tabs/AdminTab.js`

### Identity and accounts

- [Client auth state](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/auth-context.js): `src/lib/auth-context.js`
- [User profiles](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/profile.js): `src/lib/profile.js`
- [Session and auth routes](https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/auth): `src/app/api/auth`
- [User administration](https://github.com/gillandghaz/gramofon-web/blob/main/src/app/api/admin/delete-user/route.js): `src/app/api/admin/delete-user/route.js`
- [Profile photo routes](https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/profile/photo): `src/app/api/profile/photo`

### Media and catalogs

- [Private media routes](https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/media): `src/app/api/media`
- [Explore catalog routes](https://github.com/gillandghaz/gramofon-web/tree/main/src/app/api/explore): `src/app/api/explore`

### Backend and services

- [Server authorization](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/server-auth.js): `src/lib/server-auth.js`
- [Firebase Admin access](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/firebase-admin.js): `src/lib/firebase-admin.js`
- [Firebase client SDK](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/firebase.js): `src/lib/firebase.js`
- [Cloudinary administration](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/cloudinary-admin.js): `src/lib/cloudinary-admin.js`
- [Client media upload](https://github.com/gillandghaz/gramofon-web/blob/main/src/lib/cloudinary-upload.js): `src/lib/cloudinary-upload.js`
- **Firestore metadata**
- **Firebase Authentication**
- **Cloudinary media store**

### Other components

- **Browser user**

## Connections

- Browser user → Landing and auth pages: opens (evidence: `README.md`)
- Browser user → Login and registration: signs in (evidence: `README.md`)
- Browser user → Player and library UI: uses player (evidence: `README.md`)
- Browser user → Account dashboard: manages account (evidence: `README.md`)
- Browser user → Admin controls: administers (evidence: `src/components/tabs/AdminTab.js`)
- Login and registration → Firebase Authentication: authenticates with (evidence: `README.md`)
- Client auth state → Firebase client SDK: uses SDK (evidence: `src/lib/auth-context.js`)
- Client auth state → User profiles: ensures profile (evidence: `src/lib/auth-context.js`)
- Client auth state → Firestore metadata: listens to profile (evidence: `src/lib/auth-context.js`)
- Player and library UI → Firebase client SDK: uses SDK (evidence: `README.md`)
- Player and library UI → Private media routes: requests upload authorization (evidence: `README.md`)
- Private media routes → Server authorization: checks user (evidence: `src/app/api/media/sign-upload/route.js`)
- Private media routes → Firebase Admin access: reads and writes metadata (evidence: `src/app/api/media/confirm-upload/route.js`)
- Private media routes → Cloudinary administration: signs and verifies assets (evidence: `src/app/api/media/confirm-upload/route.js`)
- Firebase Admin access → Firestore metadata: accesses (evidence: `src/lib/firebase-admin.js`)
- Firebase client SDK → Firestore metadata: reads and writes (evidence: `README.md`)
- Firebase client SDK → Firebase Authentication: uses (evidence: `src/lib/firebase.js`)
- Browser user → Cloudinary media store: uploads signed media (evidence: `README.md`)
- Cloudinary administration → Cloudinary media store: signs and manages assets (evidence: `src/lib/cloudinary-admin.js`)
- Browser user → Cloudinary media store: streams media (evidence: `README.md`)
- Player and library UI → Explore catalog routes: loads shared catalog (evidence: `README.md`)
- Explore catalog routes → Server authorization: checks admin (evidence: `src/app/api/explore/confirm-upload/route.js`)
- Explore catalog routes → Firebase Admin access: stores catalog metadata (evidence: `src/app/api/explore/confirm-upload/route.js`)
- Explore catalog routes → Cloudinary administration: verifies and manages assets (evidence: `src/app/api/explore/confirm-upload/route.js`)
- Admin controls → User administration: removes users (evidence: `src/app/api/admin/delete-user/route.js`)
- User administration → Firebase Admin access: deletes account data (evidence: `src/app/api/admin/delete-user/route.js`)
- User administration → Cloudinary administration: cleans profile image (evidence: `src/app/api/admin/delete-user/route.js`)
- Session and auth routes → Server authorization: verifies sessions (evidence: `src/app/api/auth/gate/route.js`)
- Server authorization → Firebase Admin access: verifies tokens and profiles (evidence: `src/lib/server-auth.js`)
- Account dashboard → Profile photo routes: updates profile photo (evidence: `README.md`)
- Profile photo routes → Server authorization: checks user (evidence: `src/app/api/profile/photo/confirm/route.js`)
- Profile photo routes → Cloudinary administration: verifies image (evidence: `src/app/api/profile/photo/confirm/route.js`)
