# ge-m-zhang/spoticast-calendar-vue architecture

> Architecture diagram of the GitHub repository ge-m-zhang/spoticast-calendar-vue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ge-m-zhang/spoticast-calendar-vue
- Repository: https://github.com/ge-m-zhang/spoticast-calendar-vue

## Overview

##### Project Type and Purpose
- This is a single-page application (SPA) built with Vue 3 + Composition API and TypeScript.
- It visualizes podcast episode release dates (pulled from the Spotify API) in a calendar interface with rich accessibility features.

##### Main System Components
a. Client Browser
- Renders index.html and runs the compiled Vue app.
- Hosts user interactions: search, navigation, modal dialogs.
b. Web Server / Hosting Container
- Nginx server (Dockerized) serves static assets.
- Dockerfile + docker-compose.yml define the production container.
c. Vue Frontend Application
- src/main.ts bootstraps the app.
- App.vue is root component.
- src/components: UI elements (SearchSection, CalendarSection, modals).
- src/assets & public: CSS, env.js for runtime config.
d. State Management
e. API Layer
- src/api/spotify.ts & src/auth/getAccessToken.ts handle Spotify OAuth and REST calls (Axios).
f. Calendar Library
- FullCalendar integration (src/configs/fullcalendar.config.ts) renders events.
g. Utilities
- src/utils: keyboard navigation, formatters.
h. External Service
- Spotify Web API: search podcasts and fetch episodes.

##### Deployment & Dev Tooling
- Development: Vite dev server (vite.config.ts) serves the SPA with hot reload.
- Production: Build artifacts served by Nginx in a Docker container.
- Configuration injection via public/env.js (populated from environment variables in entrypoint.sh).

##### Relationships & Data Flows
- User → Browser UI → Vue Components → Pinia Store → API Layer → Spotify API → back to Store → Calendar Component → rendered on screen.
- On initial page load, Nginx serves the SPA.
- Env vars flow from Docker-compose/env files → entrypoint.sh → public/env.js → application at runtime.

##### Architectural Patterns & Design Principles
- Component-based architecture (Vue components grouped by feature).
- Unidirectional data flow: components read/write store.
- Separation of concerns:
- API logic separated in src/api and src/auth
- UI in src/components
- State in src/stores
- Configuration in src/configs
- Accessibility baked into component design (keyboard navigation util, ARIA attributes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser
    subgraph "Client Browser"
        Browser["Browser\n(index.html)"]:::ui
        EnvPublic["public/env.js"]:::infra
    end

    %% Vue Frontend Application
    subgraph "Vue Frontend Application"
        Main["src/main.ts"]:::infra
        AppComp["src/App.vue"]:::ui

        subgraph "Components"
            SearchSection["SearchSection.vue"]:::ui
            SearchBar["SearchBar.vue"]:::ui
            PodcastList["PodcastList.vue"]:::ui
            PodcastItem["PodcastItem.vue"]:::ui
            CalendarSection["CalendarSection.vue"]:::ui
            CalendarHeader["CalendarHeader.vue"]:::ui
            SpoticastCalendar["SpoticastCalendar.vue"]:::ui
            EpisodeModal["EpisodeModal.vue"]:::ui
            KeyboardNavInstr["KeyboardNavInstruction.vue"]:::ui
        end

        subgraph "Pinia Stores"
            PodcastStore["podcastStore.ts"]:::state
            EpisodeStore["episodeStore.ts"]:::state
            CalendarStore["calendarStore.ts"]:::state
            ColorStore["colorStore.ts"]:::state
        end

        subgraph "API Layer"
            SpotifyAPI["src/api/spotify.ts"]:::api
            AuthToken["src/auth/getAccessToken.ts"]:::api
        end

        FCConfig["src/configs/fullcalendar.config.ts"]:::infra

        subgraph "Utilities"
            KeyNavUtil["src/utils/keyboardNavigation.util.ts"]:::util
            CalKeyNav["src/utils/calendarKeyboardNavigation.ts"]:::util
            Formatters["src/utils/formatters.ts"]:::util
        end
    end

    %% External Service
    subgraph "External Service"
        Spotify["Spotify Web API"]:::external
    end

    %% Dev & Build Tooling
    subgraph "Development & Build Tooling"
        Vite["vite.config.ts\n(Vite Dev Server)"]:::infra
        TSconfigs["tsconfig*.json\nvitest.config.ts"]:::infra
        Package["package.json\nREADME.md"]:::infra
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        Dockerfile["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        NginxConf["nginx.default.conf"]:::infra
        Entrypoint["entrypoint.sh"]:::infra
    end

    %% Data Flow
    Browser -->|"loads SPA"| Main
    Main --> AppComp
    AppComp --> Components
    Components -->|"reads/writes"| PodcastStore
    Components -->|"reads/writes"| EpisodeStore
    Components -->|"reads/writes"| CalendarStore
    Components -->|"reads/writes"| ColorStore
    PodcastStore -->|"dispatch OAuth"| AuthToken
    PodcastStore -->|"calls"| SpotifyAPI
    SpotifyAPI -->|HTTPS| Spotify
    Spotify -->|JSON response| SpotifyAPI
    SpotifyAPI --> PodcastStore
    CalendarSection --> FCConfig
    Components --> Utilities
    EnvPublic --> Main
    Entrypoint -.->|writes| EnvPublic
    Compose -.-> Entrypoint
    Compose -.->|includes| Dockerfile
    Dockerfile -.-> NginxConf
    Dockerfile -.->|builds container| NginxConf
    Vite --> Main

    %% Click Events
    click Browser "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/index.html"
    click EnvPublic "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/public/env.js"
    click Main "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/main.ts"
    click AppComp "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/App.vue"
    click SearchSection "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/search-section/SearchSection.vue"
    click SearchBar "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/search-section/SearchBar.vue"
    click PodcastList "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/search-section/PodcastList.vue"
    click PodcastItem "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/search-section/PodcastItem.vue"
    click CalendarSection "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/calendar-section/CalendarSection.vue"
    click CalendarHeader "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/calendar-section/CalendarHeader.vue"
    click SpoticastCalendar "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/calendar-section/SpoticastCalendar.vue"
    click EpisodeModal "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/calendar-section/EpisodeModal.vue"
    click KeyboardNavInstr "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/components/KeyboardNavInstruction.vue"
    click PodcastStore "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/stores/podcastStore.ts"
    click EpisodeStore "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/stores/episodeStore.ts"
    click CalendarStore "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/stores/calendarStore.ts"
    click ColorStore "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/stores/colorStore.ts"
    click SpotifyAPI "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/api/spotify.ts"
    click AuthToken "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/auth/getAccessToken.ts"
    click FCConfig "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/configs/fullcalendar.config.ts"
    click KeyNavUtil "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/utils/keyboardNavigation.util.ts"
    click CalKeyNav "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/utils/calendarKeyboardNavigation.ts"
    click Formatters "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/src/utils/formatters.ts"
    click Vite "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/vite.config.ts"
    click Compose "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/ge-m-zhang/spoticast-calendar-vue/tree/main/Dockerfile"
    click NginxConf "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/nginx.default.conf"
    click Entrypoint "https://github.com/ge-m-zhang/spoticast-calendar-vue/blob/main/entrypoint.sh"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef state fill:#E3FFDA,stroke:#28A745,stroke-width:2px
    classDef api fill:#FFE4B5,stroke:#D2691E,stroke-width:2px
    classDef external fill:#FFDACC,stroke:#E5534B,stroke-width:2px
    classDef infra fill:#F0F0F0,stroke:#636363,stroke-width:2px
    classDef util fill:#F5E1FF,stroke:#8A2BE2,stroke-width:2px
```
