# angelrangel21/rangel-guitar architecture

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

- Interactive diagram: https://gitdiagram.com/angelrangel21/rangel-guitar
- Repository: https://github.com/angelrangel21/rangel-guitar

## Overview

Rangel Guitar is a multilingual guitar-song library and learning app. Visitors search or browse songs and artists, then view lyrics and chords; the README also documents transposition, favorites, song requests, authentication, and admin review. Learning tools provide separate practice features. The graph uses sampled search and auth code plus SOURCE INDEX references for supported internal links; README-described capabilities are retained, but unsampled route-to-service wiring is not inferred.

Main entry points: [`src/lib/supabase.ts`](https://github.com/angelrangel21/rangel-guitar/blob/master/src/lib/supabase.ts) (Supabase), [`src/components/home-client.tsx`](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/home-client.tsx) (Home browser), [`src/app/[locale]/learn/page.tsx`](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/page.tsx) (Learning hub), [`src/auth/stores/auth.stores.ts`](https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/stores/auth.stores.ts) (Auth and favorites state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Song library"]
  node_home["Song home<br/>[page.tsx]"]
  node_home_ui["Home browser<br/>[home-client.tsx]"]
  node_song_list["Song list<br/>[song-list.tsx]"]
  node_search_ui["Search UI<br/>[search.tsx]"]
  node_search_hook["Search state<br/>[useSearch.ts]"]
  node_search_service["Song search<br/>[search.service.ts]"]
  node_search_page["Search page<br/>[page.tsx]"]
  node_search_content["Search results view"]
  node_artists["Artist pages<br/>[page.tsx]"]
  node_song_detail["Song view<br/>[page.tsx]"]
  node_song_service["Song catalog<br/>[song.service.ts]"]
end

subgraph group_music["Music learning"]
  node_learning["Learning hub<br/>[page.tsx]"]
  node_chords["Chord library<br/>[page.tsx]"]
  node_scales["Scale explorer<br/>[page.tsx]"]
  node_circle["Circle of fifths<br/>[page.tsx]"]
  node_ear["Ear trainer<br/>[page.tsx]"]
  node_metronome["Metronome<br/>[page.tsx]"]
end

subgraph group_identity["Identity and favorites"]
  node_login["Login and registration<br/>[page.tsx]"]
  node_auth_provider["Auth provider<br/>[auth.provider.tsx]"]
  node_auth_store["Auth and favorites state<br/>[auth.stores.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_user_service["User profiles<br/>[user.service.ts]"]
  node_favorites["Favorites page<br/>[page.tsx]"]
  node_favorite_service["Favorite persistence"]
end

subgraph group_operations["Content operations"]
  node_request_page["Song request<br/>[page.tsx]"]
  node_request_service["Request handling"]
  node_admin_requests["Admin request review<br/>[page.tsx]"]
  node_admin_content["Song and artist management<br/>[page.tsx]"]
end

subgraph group_platform["Shared platform"]
  node_supabase[("Supabase<br/>[supabase.ts]")]
  node_server_supabase["Server Supabase client<br/>[server.ts]"]
  node_db_schema["Database schema types<br/>[database.types.ts]"]
end

node_visitor(("Visitor"))
node_auth_service_external["Supabase Auth"]

node_visitor -->|"browses"| node_home
node_home -->|"renders"| node_home_ui
node_home_ui -->|"renders"| node_song_list
node_home_ui -->|"renders"| node_search_ui
node_home_ui -->|"routes query"| node_search_page
node_search_page -->|"renders"| node_search_content
node_search_content -->|"renders"| node_search_ui
node_search_ui -->|"uses state"| node_search_hook
node_search_hook -->|"searches"| node_search_service
node_search_service -->|"queries"| node_supabase
node_home -->|"loads songs"| node_song_service
node_visitor -->|"browses artists"| node_artists
node_visitor -->|"views songs"| node_song_detail
node_visitor -->|"opens learning"| node_learning
node_learning -->|"offers tool"| node_circle
node_learning -->|"offers tool"| node_ear
node_learning -->|"offers tool"| node_metronome
node_visitor -->|"explores chords"| node_chords
node_visitor -->|"explores scales"| node_scales
node_visitor -->|"registers or signs in"| node_login
node_auth_provider -->|"updates state"| node_auth_store
node_auth_store -->|"authenticates"| node_auth_service
node_auth_service -->|"uses auth API"| node_supabase
node_auth_service_external -->|"provides auth"| node_auth_service
node_auth_store -->|"loads profile"| node_user_service
node_auth_store -->|"updates favorites"| node_favorite_service
node_favorite_service -->|"persists favorites"| node_supabase
node_visitor -->|"opens favorites"| node_favorites
node_visitor -->|"requests song"| node_request_page
node_visitor -->|"admin reviews"| node_admin_requests
node_visitor -->|"admin manages catalog"| node_admin_content
node_song_service -->|"queries catalog"| node_supabase
node_request_service -->|"uses server client"| node_server_supabase
node_supabase -->|"uses schema types"| node_db_schema
node_server_supabase -.->|"connects server auth"| node_auth_service_external

click node_home "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/page.tsx"
click node_home_ui "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/home-client.tsx"
click node_song_list "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/song-list.tsx"
click node_search_ui "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search.tsx"
click node_search_hook "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/useSearch.ts"
click node_search_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search.service.ts"
click node_search_page "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/search/page.tsx"
click node_search_content "https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search-page-content.tsx"
click node_artists "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/artists/page.tsx"
click node_song_detail "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/songs/%5Bslug%5D/page.tsx"
click node_song_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/song.service.ts"
click node_learning "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/page.tsx"
click node_chords "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/chords/page.tsx"
click node_scales "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/scales/page.tsx"
click node_circle "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/circle-of-fifths/page.tsx"
click node_ear "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/ear-trainer/page.tsx"
click node_metronome "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/metronome/page.tsx"
click node_login "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/login/page.tsx"
click node_auth_provider "https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/provider/auth.provider.tsx"
click node_auth_store "https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/stores/auth.stores.ts"
click node_auth_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/service/auth.service.ts"
click node_user_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/service/user.service.ts"
click node_favorites "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/favorites/page.tsx"
click node_favorite_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/favorites.service.ts"
click node_request_page "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/request-song/page.tsx"
click node_request_service "https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/requests-service.ts"
click node_admin_requests "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/admin/requests/page.tsx"
click node_admin_content "https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/admin/add-song/page.tsx"
click node_supabase "https://github.com/angelrangel21/rangel-guitar/blob/master/src/lib/supabase.ts"
click node_server_supabase "https://github.com/angelrangel21/rangel-guitar/blob/master/src/lib/supabase/server.ts"
click node_db_schema "https://github.com/angelrangel21/rangel-guitar/blob/master/src/types/database.types.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_home_ui,node_song_list,node_search_ui,node_search_hook,node_search_service,node_search_page,node_search_content,node_artists,node_song_detail,node_song_service toneBlue
class node_learning,node_chords,node_scales,node_circle,node_ear,node_metronome toneAmber
class node_login,node_auth_provider,node_auth_store,node_auth_service,node_user_service,node_favorites,node_favorite_service toneMint
class node_request_page,node_request_service,node_admin_requests,node_admin_content toneRose
class node_supabase,node_server_supabase,node_db_schema,node_visitor,node_auth_service_external toneIndigo
```

## Components

### Song library

- [Song home](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/page.tsx): `src/app/[locale]/page.tsx`
- [Home browser](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/home-client.tsx): `src/components/home-client.tsx`
- [Song list](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/song-list.tsx): `src/components/song-list.tsx`
- [Search UI](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search.tsx): `src/components/searching/search.tsx`
- [Search state](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/useSearch.ts): `src/components/searching/useSearch.ts`
- [Song search](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search.service.ts): `src/components/searching/search.service.ts`
- [Search page](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/search/page.tsx): `src/app/[locale]/search/page.tsx`
- [Search results view](https://github.com/angelrangel21/rangel-guitar/blob/master/src/components/searching/search-page-content.tsx): `src/components/searching/search-page-content.tsx`
- [Artist pages](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/artists/page.tsx): `src/app/[locale]/artists/page.tsx`
- [Song view](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/songs/%5Bslug%5D/page.tsx): `src/app/[locale]/songs/[slug]/page.tsx`
- [Song catalog](https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/song.service.ts): `src/services/song.service.ts`

### Music learning

- [Learning hub](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/page.tsx): `src/app/[locale]/learn/page.tsx`
- [Chord library](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/chords/page.tsx): `src/app/[locale]/chords/page.tsx`
- [Scale explorer](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/scales/page.tsx): `src/app/[locale]/scales/page.tsx`
- [Circle of fifths](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/circle-of-fifths/page.tsx): `src/app/[locale]/learn/circle-of-fifths/page.tsx`
- [Ear trainer](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/ear-trainer/page.tsx): `src/app/[locale]/learn/ear-trainer/page.tsx`
- [Metronome](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/learn/metronome/page.tsx): `src/app/[locale]/learn/metronome/page.tsx`

### Identity and favorites

- [Login and registration](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/login/page.tsx): `src/app/[locale]/login/page.tsx`
- [Auth provider](https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/provider/auth.provider.tsx): `src/auth/provider/auth.provider.tsx`
- [Auth and favorites state](https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/stores/auth.stores.ts): `src/auth/stores/auth.stores.ts`
- [Auth service](https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/service/auth.service.ts): `src/auth/service/auth.service.ts`
- [User profiles](https://github.com/angelrangel21/rangel-guitar/blob/master/src/auth/service/user.service.ts): `src/auth/service/user.service.ts`
- [Favorites page](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/favorites/page.tsx): `src/app/[locale]/favorites/page.tsx`
- [Favorite persistence](https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/favorites.service.ts): `src/services/favorites.service.ts`

### Content operations

- [Song request](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/request-song/page.tsx): `src/app/[locale]/request-song/page.tsx`
- [Request handling](https://github.com/angelrangel21/rangel-guitar/blob/master/src/services/requests-service.ts): `src/services/requests-service.ts`
- [Admin request review](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/admin/requests/page.tsx): `src/app/[locale]/admin/requests/page.tsx`
- [Song and artist management](https://github.com/angelrangel21/rangel-guitar/blob/master/src/app/%5Blocale%5D/admin/add-song/page.tsx): `src/app/[locale]/admin/add-song/page.tsx`

### Shared platform

- [Supabase](https://github.com/angelrangel21/rangel-guitar/blob/master/src/lib/supabase.ts): `src/lib/supabase.ts`
- [Server Supabase client](https://github.com/angelrangel21/rangel-guitar/blob/master/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Database schema types](https://github.com/angelrangel21/rangel-guitar/blob/master/src/types/database.types.ts): `src/types/database.types.ts`

### Other components

- **Visitor**
- **Supabase Auth**

## Connections

- Visitor → Song home: browses (evidence: `README.md`)
- Song home → Home browser: renders (evidence: `src/app/[locale]/page.tsx`)
- Home browser → Song list: renders (evidence: `src/components/home-client.tsx`)
- Home browser → Search UI: renders (evidence: `src/components/home-client.tsx`)
- Home browser → Search page: routes query (evidence: `src/components/home-client.tsx`)
- Search page → Search results view: renders (evidence: `src/app/[locale]/search/page.tsx`)
- Search results view → Search UI: renders (evidence: `src/components/searching/search-page-content.tsx`)
- Search UI → Search state: uses state (evidence: `src/components/searching/search.tsx`)
- Search state → Song search: searches (evidence: `src/components/searching/useSearch.ts`)
- Song search → Supabase: queries (evidence: `src/components/searching/search.service.ts`)
- Song home → Song catalog: loads songs (evidence: `src/app/[locale]/page.tsx`)
- Visitor → Artist pages: browses artists (evidence: `README.md`)
- Visitor → Song view: views songs (evidence: `README.md`)
- Visitor → Learning hub: opens learning (evidence: `README.md`)
- Learning hub → Circle of fifths: offers tool (evidence: `README.md`)
- Learning hub → Ear trainer: offers tool (evidence: `README.md`)
- Learning hub → Metronome: offers tool (evidence: `README.md`)
- Visitor → Chord library: explores chords (evidence: `README.md`)
- Visitor → Scale explorer: explores scales (evidence: `README.md`)
- Visitor → Login and registration: registers or signs in (evidence: `README.md`)
- Auth provider → Auth and favorites state: updates state (evidence: `src/auth/provider/auth.provider.tsx`)
- Auth and favorites state → Auth service: authenticates (evidence: `src/auth/stores/auth.stores.ts`)
- Auth service → Supabase: uses auth API (evidence: `src/auth/service/auth.service.ts`)
- Supabase Auth → Auth service: provides auth (evidence: `README.md`)
- Auth and favorites state → User profiles: loads profile (evidence: `src/auth/stores/auth.stores.ts`)
- Auth and favorites state → Favorite persistence: updates favorites (evidence: `src/auth/stores/auth.stores.ts`)
- Favorite persistence → Supabase: persists favorites (evidence: `src/services/favorites.service.ts`)
- Visitor → Favorites page: opens favorites (evidence: `README.md`)
- Visitor → Song request: requests song (evidence: `README.md`)
- Visitor → Admin request review: admin reviews (evidence: `README.md`)
- Visitor → Song and artist management: admin manages catalog (evidence: `README.md`)
- Song catalog → Supabase: queries catalog (evidence: `src/services/song.service.ts`)
- Request handling → Server Supabase client: uses server client (evidence: `src/services/requests-service.ts`)
- Supabase → Database schema types: uses schema types (evidence: `src/lib/supabase.ts`)
- Server Supabase client → Supabase Auth: connects server auth
