# faiz4n/sonara architecture

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

- Interactive diagram: https://gitdiagram.com/faiz4n/sonara
- Repository: https://github.com/faiz4n/sonara

## Overview

1. **Overall shape**
   - Sonara is a two-tier full-stack app: a **React/Vite frontend** and a **Node.js/Express backend**.
   - The frontend is a single-page application for discovery and artist workflows.
   - The backend exposes a REST API for authentication, track management, album management, and file upload/storage.

2. **Backend entry and layering**
   - `Backend/server.js` starts the service, while `Backend/src/app.js` assembles middleware and routes.
   - The backend is organized into a typical layered structure:
     - **routes** define HTTP endpoints,
     - **controllers** implement request handling,
     - **models** define MongoDB entities,
     - **middlewares** enforce auth/guard logic,
     - **services** encapsulate external integrations such as file storage,
     - **db** holds the MongoDB connection setup.
   - `seed.js` is a separate bootstrap path for populating initial data.

3. **Backend domain model**
   - The main persisted entities are `user`, `music`, and `album`.
   - This implies two core content types:
     - individual **tracks/music items** with metadata and uploaded media,
     - **albums** that organize tracks into collections.
   - User identity is central because many endpoints are ownership-based, especially for artist actions like upload/delete/create.

4. **Backend API boundaries**
   - Authentication lives under `auth.routes.js` and `auth.controller.js`.
   - Music and album operations are handled under `music.routes.js` and `music.controller.js`.
   - The API shape is centered around `/api/auth` and `/api/music`, with album endpoints nested under the music namespace.
   - Some endpoints are public for discovery, while others are protected for the authenticated artist workflow.

5. **Auth and access control**
   - `auth.middleware.js` is the main boundary between public access and protected artist actions.
   - The readme indicates JWT-based authentication, so the backend likely issues tokens on login and validates them on protected requests.
   - Ownership checks are important in the album/track management flows, especially for delete and creator-only operations.

6. **File upload and external storage**
   - `storage.service.js` is a dedicated abstraction for media upload/storage.
   - The stack uses **Multer** for incoming multipart file handling and **ImageKit** for persistent file hosting.
   - This means media does not stay only on the API server; the backend acts as an ingestion and metadata/pointer manager, while actual asset delivery comes from the storage provider.

7. **Backend data flow**
   - For upload actions, the flow is: client submits multipart form data → route/controller → auth/validation middleware if needed → Multer parses files → storage service sends assets to ImageKit → controller persists MongoDB metadata through models.
   - For read actions, controllers query MongoDB models and return track/album documents to the frontend.
   - For delete actions, controllers verify ownership, remove the MongoDB record, and likely coordinate cleanup of stored assets or references.

8. **Frontend application shell**
   - The frontend is a Vite-built React application (`main.jsx`, `App.jsx`) with route-based navigation.
   - `src/services/api.js` and the feature services (`auth.service.js`, `music.service.js`) form the network boundary to the backend.
   - This separation keeps component code focused on UI/state, while service modules centralize API requests and payload shaping.

9. **Frontend state and route protection**
   - `authContext.jsx` manages login/session state for the app.
   - `PlayerContext.jsx` suggests a global playback state layer, even though the player feature is still in progress.
   - `ProtectedRoute.jsx` and `GuestRoute.jsx` gate access to authenticated pages versus login/register flows, which mirrors the backend auth boundary.

10. **Frontend feature areas**
   - `pages/` contains the main screens: home, login, register, albums, album detail, profile, and `ArtistStudio`.
   - `components/forms/` hosts the main user interactions: login/register, track upload, and album creation.
   - `components/artist/`, `components/album/`, and `components/music/` separate artist management from public discovery and album detail rendering.
   - `components/layout/` provides the persistent shell such as sidebar and headers, while `components/UI/` contains reusable primitives.

11. **User journeys**
   - **Guest flow:** users land on discovery pages, can browse music/albums, and are routed to login/register for gated actions.
   - **Authenticated listener/artist flow:** once signed in, the app can show profile data and allow access to protected resources.
   - **Artist studio flow:** artists upload tracks, create albums from selected tracks, inspect their own catalog, and delete owned content.
   - **Album detail flow:** album pages show header/metadata and track listings via modularized album components.

12. **Responsive and deployment boundaries**
   - The frontend is styled with Tailwind and has explicit mobile-friendly layout components such as mobile sidebar variants.
   - The frontend has a `vercel.json`, suggesting separate frontend deployment from the backend API.
   - The backend and frontend therefore behave like independently deployable services, connected only through the API contract.

13. **Key architectural takeaway**
   - The system is built around a clear split: **React handles presentation, navigation, and client state; Express/MongoDB handle identity, catalog data, ownership checks, and media ingestion**.
   - The most important diagram edges are:
     - browser/UI → frontend service layer → backend API,
     - backend controllers → auth/middleware/models,
     - backend storage service → ImageKit,
     - backend models → MongoDB.

Main entry points: [`Frontend/src/App.jsx`](https://github.com/faiz4n/sonara/blob/main/Frontend/src/App.jsx) (App), [`Frontend/src/services/api.js`](https://github.com/faiz4n/sonara/blob/main/Frontend/src/services/api.js) (API client), [`Backend/src/controllers/auth.controller.js`](https://github.com/faiz4n/sonara/blob/main/Backend/src/controllers/auth.controller.js) (Controllers), [`Backend/src/routes/auth.routes.js`](https://github.com/faiz4n/sonara/blob/main/Backend/src/routes/auth.routes.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_main["App shell<br/>react entry<br/>[main.jsx]"]
  node_fe_app["App<br/>router shell<br/>[App.jsx]"]
  node_fe_ctx_auth(("Auth state<br/>react context<br/>[authContext.jsx]"))
  node_fe_ctx_player(("Player state<br/>react context<br/>[PlayerContext.jsx]"))
  node_fe_guards["Route guards<br/>route protection<br/>[ProtectedRoute.jsx]"]
  node_fe_services["API client<br/>service layer<br/>[api.js]"]
  node_fe_home["Discovery pages<br/>[HomePage.jsx]"]
  node_fe_auth_forms["Auth forms<br/>[LoginForm.jsx]"]
  node_fe_artist_forms["Artist forms"]
  node_fe_album_ui["Album UI<br/>feature components<br/>[AlbumHeader.jsx]"]
  node_fe_music_ui["Music UI<br/>feature components<br/>[MusicList.jsx]"]
end

subgraph group_backend["Backend"]
  node_be_server["Server<br/>node entry<br/>[server.js]"]
  node_be_app["Express app<br/>api bootstrap<br/>[app.js]"]
  node_be_routes["API routes<br/>[auth.routes.js]"]
  node_be_controllers["Controllers<br/>request handlers<br/>[auth.controller.js]"]
  node_be_guard["Auth middleware<br/>access control<br/>[auth.middleware.js]"]
  node_be_models[("Domain models<br/>mongoose models<br/>[user.model.js]")]
  node_be_db[("MongoDB<br/>database connection<br/>[db.js]")]
  node_be_storage["Storage service<br/>media integration<br/>[storage.service.js]"]
  node_be_seed["Seed data<br/>bootstrap script<br/>[seed.js]"]
end

node_fe_main -->|"boots"| node_fe_app
node_fe_app -->|"uses"| node_fe_ctx_auth
node_fe_app -->|"uses"| node_fe_ctx_player
node_fe_app -->|"routes"| node_fe_guards
node_fe_app -->|"navigates"| node_fe_home
node_fe_home -->|"renders"| node_fe_music_ui
node_fe_home -->|"renders"| node_fe_album_ui
node_fe_auth_forms -->|"calls"| node_fe_services
node_fe_artist_forms -->|"calls"| node_fe_services
node_fe_music_ui -->|"fetches"| node_fe_services
node_fe_album_ui -->|"fetches"| node_fe_services
node_fe_services -->|"HTTP API"| node_be_routes
node_be_server -->|"starts"| node_be_app
node_be_app -->|"mounts"| node_be_routes
node_be_routes -->|"delegates"| node_be_controllers
node_be_controllers -->|"protects"| node_be_guard
node_be_controllers -->|"reads/writes"| node_be_models
node_be_models -->|"connects"| node_be_db
node_be_controllers -->|"uploads"| node_be_storage
node_be_storage -->|"persists refs"| node_be_db
node_be_seed -->|"seeds"| node_be_db
node_fe_guards -.->|"aligns with"| node_be_routes

click node_fe_main "https://github.com/faiz4n/sonara/blob/main/Frontend/src/main.jsx"
click node_fe_app "https://github.com/faiz4n/sonara/blob/main/Frontend/src/App.jsx"
click node_fe_ctx_auth "https://github.com/faiz4n/sonara/blob/main/Frontend/src/context/authContext.jsx"
click node_fe_ctx_player "https://github.com/faiz4n/sonara/blob/main/Frontend/src/context/PlayerContext.jsx"
click node_fe_guards "https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/ProtectedRoute.jsx"
click node_fe_services "https://github.com/faiz4n/sonara/blob/main/Frontend/src/services/api.js"
click node_fe_home "https://github.com/faiz4n/sonara/blob/main/Frontend/src/pages/HomePage.jsx"
click node_fe_auth_forms "https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/forms/LoginForm.jsx"
click node_fe_artist_forms "https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/forms/UploadMusicForm.jsx"
click node_fe_album_ui "https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/album/AlbumHeader.jsx"
click node_fe_music_ui "https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/music/MusicList.jsx"
click node_be_server "https://github.com/faiz4n/sonara/blob/main/Backend/server.js"
click node_be_app "https://github.com/faiz4n/sonara/blob/main/Backend/src/app.js"
click node_be_routes "https://github.com/faiz4n/sonara/blob/main/Backend/src/routes/auth.routes.js"
click node_be_controllers "https://github.com/faiz4n/sonara/blob/main/Backend/src/controllers/auth.controller.js"
click node_be_guard "https://github.com/faiz4n/sonara/blob/main/Backend/src/middlewares/auth.middleware.js"
click node_be_models "https://github.com/faiz4n/sonara/blob/main/Backend/src/models/user.model.js"
click node_be_db "https://github.com/faiz4n/sonara/blob/main/Backend/src/db/db.js"
click node_be_storage "https://github.com/faiz4n/sonara/blob/main/Backend/src/services/storage.service.js"
click node_be_seed "https://github.com/faiz4n/sonara/blob/main/Backend/seed.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_fe_main,node_fe_app,node_fe_ctx_auth,node_fe_ctx_player,node_fe_guards,node_fe_services,node_fe_home,node_fe_auth_forms,node_fe_artist_forms,node_fe_album_ui,node_fe_music_ui toneBlue
class node_be_server,node_be_app,node_be_routes,node_be_controllers,node_be_guard,node_be_models,node_be_db,node_be_storage,node_be_seed toneAmber
```

## Components

### Frontend

React/Vite client, UI state, and API-facing feature modules

- [App shell](https://github.com/faiz4n/sonara/blob/main/Frontend/src/main.jsx): react entry · Vite/React bootstrap and top-level router composition · `Frontend/src/main.jsx`
- [App](https://github.com/faiz4n/sonara/blob/main/Frontend/src/App.jsx): router shell · Defines the client route map and app composition · `Frontend/src/App.jsx`
- [Auth state](https://github.com/faiz4n/sonara/blob/main/Frontend/src/context/authContext.jsx): react context · Holds session/login state for the client · `Frontend/src/context/authContext.jsx`
- [Player state](https://github.com/faiz4n/sonara/blob/main/Frontend/src/context/PlayerContext.jsx): react context · Global playback state and player coordination · `Frontend/src/context/PlayerContext.jsx`
- [Route guards](https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/ProtectedRoute.jsx): route protection · Protects authenticated pages and guest-only flows · `Frontend/src/components/ProtectedRoute.jsx`
- [API client](https://github.com/faiz4n/sonara/blob/main/Frontend/src/services/api.js): service layer · Central HTTP boundary plus auth and music service calls · `Frontend/src/services/api.js`
- [Discovery pages](https://github.com/faiz4n/sonara/blob/main/Frontend/src/pages/HomePage.jsx): pages · Public landing, albums, album detail, profile, and studio screens · `Frontend/src/pages/HomePage.jsx`
- [Auth forms](https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/forms/LoginForm.jsx): forms · Login and registration flows · `Frontend/src/components/forms/LoginForm.jsx`
- [Artist forms](https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/forms/UploadMusicForm.jsx): forms · Upload track and create album workflows · `Frontend/src/components/forms/UploadMusicForm.jsx`
- [Album UI](https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/album/AlbumHeader.jsx): feature components · Album header, actions, and track listing views · `Frontend/src/components/album/AlbumHeader.jsx`
- [Music UI](https://github.com/faiz4n/sonara/blob/main/Frontend/src/components/music/MusicList.jsx): feature components · Music and album list/item presentation for discovery · `Frontend/src/components/music/MusicList.jsx`

### Backend

Express API, domain logic, persistence, and media ingestion

- [Server](https://github.com/faiz4n/sonara/blob/main/Backend/server.js): node entry · Starts the backend service process · `Backend/server.js`
- [Express app](https://github.com/faiz4n/sonara/blob/main/Backend/src/app.js): api bootstrap · Assembles middleware and mounts API routes · `Backend/src/app.js`
- [API routes](https://github.com/faiz4n/sonara/blob/main/Backend/src/routes/auth.routes.js): routes · Auth and music route namespaces · `Backend/src/routes/auth.routes.js`
- [Controllers](https://github.com/faiz4n/sonara/blob/main/Backend/src/controllers/auth.controller.js): request handlers · Auth and music request orchestration · `Backend/src/controllers/auth.controller.js`
- [Auth middleware](https://github.com/faiz4n/sonara/blob/main/Backend/src/middlewares/auth.middleware.js): access control · JWT-based request protection and ownership boundary · `Backend/src/middlewares/auth.middleware.js`
- [Domain models](https://github.com/faiz4n/sonara/blob/main/Backend/src/models/user.model.js): mongoose models · User, track/music, and album persistence schemas · `Backend/src/models/user.model.js`
- [MongoDB](https://github.com/faiz4n/sonara/blob/main/Backend/src/db/db.js): database connection · Mongo connection setup and persistence gateway · `Backend/src/db/db.js`
- [Storage service](https://github.com/faiz4n/sonara/blob/main/Backend/src/services/storage.service.js): media integration · Uploads media to external file hosting · `Backend/src/services/storage.service.js`
- [Seed data](https://github.com/faiz4n/sonara/blob/main/Backend/seed.js): bootstrap script · Initial data population path · `Backend/seed.js`

## Connections

- App shell → App: boots · Client bootstrap renders the application router
- App → Auth state: uses · App reads session state from auth context
- App → Player state: uses · App wires global playback state
- App → Route guards: routes · Route tree applies guest/protected gates
- App → Discovery pages: navigates · App surfaces public and logged-in pages
- Discovery pages → Music UI: renders · Discovery pages compose music and album lists
- Discovery pages → Album UI: renders · Album pages compose album-specific UI
- Auth forms → API client: calls · Login/register submit through the API client
- Artist forms → API client: calls · Upload and album creation use the API client
- Music UI → API client: fetches · Lists and detail views load catalog data
- Album UI → API client: fetches · Album views load and mutate album data
- API client → API routes: HTTP API · Frontend service layer talks to backend routes
- Server → Express app: starts · Server process launches the Express app
- Express app → API routes: mounts · Express app mounts auth and music namespaces
- API routes → Controllers: delegates · Routes forward requests to controllers
- Controllers → Auth middleware: protects · Protected operations pass through auth checks
- Controllers → Domain models: reads/writes · Controllers persist and query domain documents
- Domain models → MongoDB: connects · Models use the MongoDB connection
- Controllers → Storage service: uploads · Media ingestion is delegated to storage integration
- Storage service → MongoDB: persists refs · Stored asset metadata is associated with catalog records
- Seed data → MongoDB: seeds · Seed script populates MongoDB
- Route guards → API routes: aligns with · Client route protection mirrors backend access control