# aaronhubhachen/spotify-fortune-cookie architecture

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

- Interactive diagram: https://gitdiagram.com/aaronhubhachen/spotify-fortune-cookie
- Repository: https://github.com/aaronhubhachen/spotify-fortune-cookie

## Overview

Spotify Fortune Cookie lets a user sign in with Spotify, request a daily fortune derived from listening history, and view the fortune with its selected track. The page caches the daily result in browser storage; the API fetches recent and top tracks, normalizes a selected track, and builds the fortune. The README also describes responsive dark-mode UI and secure authentication. Source excerpts confirm the main page, authentication, and fortune API wiring; other presentation details are documented but not independently inspected.

Main entry points: [`app/page.tsx`](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/page.tsx) (Home page), [`app/api/fortune/route.ts`](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts) (Fortune endpoint), [`app/api/auth/auth.config.ts`](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/auth/auth.config.ts) (Spotify auth config), [`app/layout.tsx`](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/layout.tsx) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_home["Home page<br/>[page.tsx]"]
  node_display["Fortune display<br/>[FortuneDisplay.tsx]"]
  node_layout["Page layout<br/>[Layout.tsx]"]
  node_root["Root layout<br/>[layout.tsx]"]
  node_browser_storage[("Browser local storage")]
end

subgraph group_identity["Spotify authentication"]
  node_session_provider["Session provider"]
  node_auth_route["Auth handler<br/>[route.ts]"]
  node_auth_config["Spotify auth config<br/>[auth.config.ts]"]
end

subgraph group_fortune["Fortune generation"]
  node_fortune_api["Fortune endpoint<br/>[route.ts]"]
  node_track_fetch["Listening history fetch<br/>[route.ts]"]
  node_fortune_generator["Track selection and fortune<br/>[route.ts]"]
end

node_user(("User"))
node_spotify{{"Spotify services"}}

node_user -->|"uses"| node_home
node_home -->|"reads session"| node_session_provider
node_home -->|"signs in or out"| node_auth_route
node_root -->|"provides session"| node_session_provider
node_root -->|"renders"| node_home
node_home -->|"renders within"| node_layout
node_home -->|"passes fortune"| node_display
node_home -->|"reads and writes"| node_browser_storage
node_auth_route -->|"configures handler"| node_auth_config
node_auth_config -.->|"authorizes account"| node_spotify
node_home -->|"requests fortune"| node_fortune_api
node_fortune_api -->|"gets session"| node_auth_config
node_fortune_api -->|"fetches listening data"| node_track_fetch
node_track_fetch -->|"requests recent and top tracks"| node_spotify
node_fortune_api -->|"generates fortune"| node_fortune_generator
node_fortune_generator -->|"returns result"| node_fortune_api

click node_home "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/page.tsx"
click node_display "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/FortuneDisplay.tsx"
click node_layout "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/Layout.tsx"
click node_root "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/layout.tsx"
click node_session_provider "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/SessionProvider.tsx"
click node_auth_route "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/auth/%5B...nextauth%5D/route.ts"
click node_auth_config "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/auth/auth.config.ts"
click node_fortune_api "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts"
click node_track_fetch "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts"
click node_fortune_generator "https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.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_display,node_layout,node_root,node_browser_storage,node_user toneBlue
class node_session_provider,node_auth_route,node_auth_config toneAmber
class node_fortune_api,node_track_fetch,node_fortune_generator toneMint
class node_spotify toneIndigo
```

## Components

### Web experience

- [Home page](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/page.tsx): `app/page.tsx`
- [Fortune display](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/FortuneDisplay.tsx): `components/FortuneDisplay.tsx`
- [Page layout](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/Layout.tsx): `components/Layout.tsx`
- [Root layout](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/layout.tsx): `app/layout.tsx`
- **Browser local storage**

### Spotify authentication

- [Session provider](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/components/SessionProvider.tsx): `components/SessionProvider.tsx`
- [Auth handler](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/auth/%5B...nextauth%5D/route.ts): `app/api/auth/[...nextauth]/route.ts`
- [Spotify auth config](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/auth/auth.config.ts): `app/api/auth/auth.config.ts`

### Fortune generation

- [Fortune endpoint](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts): `app/api/fortune/route.ts`
- [Listening history fetch](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts): `app/api/fortune/route.ts`
- [Track selection and fortune](https://github.com/aaronhubhachen/spotify-fortune-cookie/blob/main/app/api/fortune/route.ts): `app/api/fortune/route.ts`

### Other components

- **User**
- **Spotify services**

## Connections

- User → Home page: uses
- Home page → Session provider: reads session
- Home page → Auth handler: signs in or out
- Root layout → Session provider: provides session
- Root layout → Home page: renders
- Home page → Page layout: renders within
- Home page → Fortune display: passes fortune
- Home page → Browser local storage: reads and writes
- Auth handler → Spotify auth config: configures handler
- Spotify auth config → Spotify services: authorizes account
- Home page → Fortune endpoint: requests fortune
- Fortune endpoint → Spotify auth config: gets session
- Fortune endpoint → Listening history fetch: fetches listening data
- Listening history fetch → Spotify services: requests recent and top tracks
- Fortune endpoint → Track selection and fortune: generates fortune
- Track selection and fortune → Fortune endpoint: returns result