# gabrieltembra/trackonnections architecture

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

- Interactive diagram: https://gitdiagram.com/gabrieltembra/trackonnections
- Repository: https://github.com/gabrieltembra/trackonnections

## Overview

Trackonnections is a React music-and-discovery app: users sign in, connect a music source, view listening activity in a feed and privacy-approximate map, find nearby venues and events, and ask DJ Gabriel for music analysis or event recommendations. The graph preserves the documented Spotify, ListenBrainz, Last.fm, OpenStreetMap, Ticketmaster, and Groq branches. Backend production wiring is documented and partly sampled; unsampled screen and service internals are represented at their exact tree paths without inferring undocumented calls.

Main entry points: [`frontend/src/context/MusicContext.jsx`](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/MusicContext.jsx) (Music state), [`functions/index.js`](https://github.com/gabrieltembra/trackonnections/blob/main/functions/index.js) (Production API), [`frontend/src/App.jsx`](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/App.jsx) (React app), [`frontend/src/screens/MapScreen.jsx`](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/MapScreen.jsx) (Music map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App experience"]
  node_app["React app<br/>[App.jsx]"]
  node_login["Login screen<br/>[LoginScreen.jsx]"]
  node_feed["Music feed<br/>[FeedScreen.jsx]"]
  node_map["Music map<br/>[MapScreen.jsx]"]
  node_dj["DJ Gabriel<br/>[DjDaniScreen.jsx]"]
  node_profile["User profile<br/>[ProfileScreen.jsx]"]
end

subgraph group_music["Music sources"]
  node_musicctx["Music state<br/>[MusicContext.jsx]"]
  node_spotify["Spotify client<br/>[spotifyApi.js]"]
  node_player["Spotify player<br/>[spotifyPlayer.js]"]
  node_listenbrainz["ListenBrainz client<br/>[listenbrainzApi.js]"]
  node_lastfm["Last.fm client<br/>[lastfmApi.js]"]
end

subgraph group_discovery["Local discovery"]
  node_geo["Location privacy<br/>[geo.js]"]
  node_nearby["Nearby venues<br/>[nearbyPlaces.js]"]
  node_events["Event search<br/>[eventsApi.js]"]
  node_djclient["DJ client<br/>[djDani.js]"]
end

subgraph group_server["API services"]
  node_api["Production API<br/>[index.js]"]
  node_devroutes["Local API routes"]
end

subgraph group_state["Identity and state"]
  node_firebase["Firebase config<br/>[firebase.js]"]
  node_auth["Auth state<br/>[AuthContext.jsx]"]
  node_profilectx["Profile state<br/>[ProfileContext.jsx]"]
  node_storage[("Local storage<br/>[storage.js]")]
end

node_listener(("Listener"))
node_firebaseauth["Firebase Auth"]
node_spotifyapi["Spotify API"]
node_lbapi["ListenBrainz API"]
node_lastfmapi["Last.fm API"]
node_osm["OpenStreetMap"]
node_ticketmaster["Ticketmaster API"]
node_groq["Groq API"]

node_listener -->|"uses"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_feed
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_dj
node_app -->|"routes to"| node_profile
node_login -->|"signs in"| node_auth
node_auth -->|"uses"| node_firebase
node_firebase -->|"authenticates"| node_firebaseauth
node_profile -->|"edits"| node_profilectx
node_profilectx -->|"reads/writes"| node_storage
node_feed -->|"reads music"| node_musicctx
node_musicctx -->|"requests data"| node_spotify
node_musicctx -->|"requests data"| node_listenbrainz
node_musicctx -->|"requests data"| node_lastfm
node_spotify -->|"OAuth / data"| node_spotifyapi
node_listenbrainz -->|"fetches listens"| node_lbapi
node_lastfm -->|"requests data"| node_api
node_api -->|"proxies requests"| node_lastfmapi
node_musicctx -->|"loads playback"| node_player
node_player -->|"plays tracks"| node_spotifyapi
node_map -->|"reads now playing"| node_musicctx
node_map -->|"approximates location"| node_geo
node_map -->|"finds venues"| node_nearby
node_nearby -->|"queries places"| node_osm
node_map -->|"searches events"| node_events
node_events -->|"requests nearby events"| node_api
node_api -->|"queries events"| node_ticketmaster
node_dj -->|"reads music profile"| node_musicctx
node_dj -->|"uses event results"| node_events
node_dj -->|"requests analysis"| node_djclient
node_djclient -->|"sends DJ request"| node_api
node_api -->|"requests completion"| node_groq
node_api -->|"verifies token"| node_firebaseauth
node_devroutes -.->|"calls AI"| node_groq
node_devroutes -.->|"queries events"| node_ticketmaster
node_devroutes -.->|"proxies requests"| node_lastfmapi

click node_app "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/LoginScreen.jsx"
click node_feed "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/FeedScreen.jsx"
click node_map "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/MapScreen.jsx"
click node_dj "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/DjDaniScreen.jsx"
click node_profile "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/ProfileScreen.jsx"
click node_musicctx "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/MusicContext.jsx"
click node_spotify "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/spotifyApi.js"
click node_player "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/spotifyPlayer.js"
click node_listenbrainz "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/listenbrainzApi.js"
click node_lastfm "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/lastfmApi.js"
click node_geo "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/utils/geo.js"
click node_nearby "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/nearbyPlaces.js"
click node_events "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/eventsApi.js"
click node_djclient "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/djDani.js"
click node_firebase "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/firebase.js"
click node_auth "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/AuthContext.jsx"
click node_profilectx "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/ProfileContext.jsx"
click node_storage "https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/utils/storage.js"
click node_api "https://github.com/gabrieltembra/trackonnections/blob/main/functions/index.js"
click node_devroutes "https://github.com/gabrieltembra/trackonnections/tree/main/backend/routes"

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_app,node_login,node_feed,node_map,node_dj,node_profile toneBlue
class node_musicctx,node_spotify,node_player,node_listenbrainz,node_lastfm toneAmber
class node_geo,node_nearby,node_events,node_djclient,node_spotifyapi,node_lbapi,node_lastfmapi,node_ticketmaster,node_groq toneMint
class node_api,node_devroutes toneRose
class node_firebase,node_auth,node_profilectx,node_storage,node_listener,node_firebaseauth,node_osm toneIndigo
```

## Components

### App experience

- [React app](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login screen](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/LoginScreen.jsx): `frontend/src/screens/LoginScreen.jsx`
- [Music feed](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/FeedScreen.jsx): `frontend/src/screens/FeedScreen.jsx`
- [Music map](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/MapScreen.jsx): `frontend/src/screens/MapScreen.jsx`
- [DJ Gabriel](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/DjDaniScreen.jsx): `frontend/src/screens/DjDaniScreen.jsx`
- [User profile](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/screens/ProfileScreen.jsx): `frontend/src/screens/ProfileScreen.jsx`

### Music sources

- [Music state](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/MusicContext.jsx): `frontend/src/context/MusicContext.jsx`
- [Spotify client](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/spotifyApi.js): `frontend/src/services/spotifyApi.js`
- [Spotify player](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/spotifyPlayer.js): `frontend/src/services/spotifyPlayer.js`
- [ListenBrainz client](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/listenbrainzApi.js): `frontend/src/services/listenbrainzApi.js`
- [Last.fm client](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/lastfmApi.js): `frontend/src/services/lastfmApi.js`

### Local discovery

- [Location privacy](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/utils/geo.js): `frontend/src/utils/geo.js`
- [Nearby venues](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/nearbyPlaces.js): `frontend/src/services/nearbyPlaces.js`
- [Event search](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/eventsApi.js): `frontend/src/services/eventsApi.js`
- [DJ client](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/services/djDani.js): `frontend/src/services/djDani.js`

### API services

- [Production API](https://github.com/gabrieltembra/trackonnections/blob/main/functions/index.js): `functions/index.js`
- [Local API routes](https://github.com/gabrieltembra/trackonnections/tree/main/backend/routes): `backend/routes`

### Identity and state

- [Firebase config](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/firebase.js): `frontend/src/firebase.js`
- [Auth state](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Profile state](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/context/ProfileContext.jsx): `frontend/src/context/ProfileContext.jsx`
- [Local storage](https://github.com/gabrieltembra/trackonnections/blob/main/frontend/src/utils/storage.js): `frontend/src/utils/storage.js`

### Other components

- **Listener**
- **Firebase Auth**
- **Spotify API**
- **ListenBrainz API**
- **Last.fm API**
- **OpenStreetMap**
- **Ticketmaster API**
- **Groq API**

## Connections

- Listener → React app: uses
- React app → Login screen: routes to
- React app → Music feed: routes to
- React app → Music map: routes to
- React app → DJ Gabriel: routes to
- React app → User profile: routes to
- Login screen → Auth state: signs in
- Auth state → Firebase config: uses
- Firebase config → Firebase Auth: authenticates
- User profile → Profile state: edits
- Profile state → Local storage: reads/writes
- Music feed → Music state: reads music
- Music state → Spotify client: requests data
- Music state → ListenBrainz client: requests data
- Music state → Last.fm client: requests data
- Spotify client → Spotify API: OAuth / data
- ListenBrainz client → ListenBrainz API: fetches listens
- Last.fm client → Production API: requests data
- Production API → Last.fm API: proxies requests
- Music state → Spotify player: loads playback
- Spotify player → Spotify API: plays tracks
- Music map → Music state: reads now playing
- Music map → Location privacy: approximates location
- Music map → Nearby venues: finds venues
- Nearby venues → OpenStreetMap: queries places
- Music map → Event search: searches events
- Event search → Production API: requests nearby events
- Production API → Ticketmaster API: queries events
- DJ Gabriel → Music state: reads music profile
- DJ Gabriel → Event search: uses event results
- DJ Gabriel → DJ client: requests analysis
- DJ client → Production API: sends DJ request
- Production API → Groq API: requests completion
- Production API → Firebase Auth: verifies token
- Local API routes → Groq API: calls AI
- Local API routes → Ticketmaster API: queries events
- Local API routes → Last.fm API: proxies requests