# dipstick713/nekomi architecture

> Architecture diagram of the GitHub repository dipstick713/nekomi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dipstick713/nekomi
- Repository: https://github.com/dipstick713/nekomi

## Overview

##### Main components
- Frontend (Nuxt 3 SPA)
- Vue components (pages/, components/, app.vue)
- Composables (composables/user.ts)
- Middleware (middleware/auth.ts)
- Backend services (Supabase)
- Authentication (Supabase OAuth integration)
- Database (PostgreSQL tables: users, songs, votes, playlists, members)
- Realtime (WebSocket/Realtime subscriptions)
- External API (Spotify)
- OAuth token endpoint
- Search & metadata endpoints
- Hosting/Deployment
- Static assets (public/) served by Vercel/Netlify or CDN
- Environment configuration (.env)

##### Relationships and data flows
- Browser ↔ Nuxt frontend
- User loads SPAs, navigates pages, triggers UI events.
- Nuxt frontend ↔ Supabase client SDK
- Auth flows (sign-in via Spotify OAuth redirect)
- CRUD on playlists, songs, votes via REST/Realtime
- Realtime subscriptions push updates to UI
- Nuxt frontend ↔ Spotify Web API
- Fetch user profile, track metadata, search results
- Supabase Realtime → Nuxt frontend
- Push vote / song addition / leaderboard changes
- Environment (.env)
- Holds SUPABASE_URL, SUPABASE_KEY, SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET

##### Architectural patterns & design principles
- Single Page Application (SPA) pattern via Nuxt 3
- Composable-based state management (Vue 3 Composition API)
- Middleware for route protection (auth guard)
- Event-driven updates via Supabase Realtime (Pub/Sub)
- Third-party integration pattern (Spotify OAuth + REST calls)

##### Final touch points
1. User logs in
2. Create playlist
3. /vote songs
4. Real-time UI updates
- Components, services, and flows from the file tree / README (e.g., middleware/auth.ts, composables/user.ts, pages folder, Supabase tables) are represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Nuxt SPA
    subgraph "Nuxt SPA"
        direction TB
        NuxtConfig["nuxt.config.ts"]:::frontend
        AppVue["app.vue"]:::frontend
        subgraph "Pages" 
            direction TB
            IndexPage["pages/index.vue"]:::frontend
            CreatePage["pages/create.vue"]:::frontend
            AddPage["pages/add.vue"]:::frontend
            ConfirmPage["pages/confirm.vue"]:::frontend
            UserPage["pages/user.vue"]:::frontend
            PlaylistPage["pages/playlist/[id].vue"]:::frontend
        end
        subgraph "Components"
            direction TB
            AddSongComp["components/AddSong.vue"]:::frontend
            HeroComp["components/Hero.vue"]:::frontend
            LeaderBoardComp["components/LeaderBoard.vue"]:::frontend
            PlaylistComp["components/Playlist.vue"]:::frontend
            SidebarComp["components/Sidebar.vue"]:::frontend
            VoteListComp["components/VoteList.vue"]:::frontend
        end
        ComposableUser["composables/user.ts"]:::frontend
        MiddlewareAuth["middleware/auth.ts"]:::frontend
        EnvFile[".env.example"]:::frontend
        ReadmeFile["README.md"]:::frontend
        PublicDir["public/"]:::frontend
        TsconfigRoot["tsconfig.json"]:::frontend
        TsconfigServer["server/tsconfig.json"]:::frontend
    end

    %% Supabase Cloud
    subgraph "Supabase" 
        direction TB
        SupabaseAuth["Auth Service"]:::backend
        SupabaseRealtime["Realtime Service"]:::backend
        SupabaseDB["PostgreSQL Database"]:::database
    end

    %% Spotify API
    SpotifyAPI["Spotify Web API"]:::external

    %% Connections
    User -->|"uses SPA"| NuxtConfig
    NuxtConfig -->|initiates SPA| AppVue
    AppVue -->|"renders pages/components"| IndexPage
    AppVue -->|renders pages/components| CreatePage
    AppVue -->|renders pages/components| PlaylistPage

    AppVue -->|"Composables & Middleware"| ComposableUser
    AppVue -->|"Route Guard"| MiddlewareAuth

    NuxtConfig -->|loads env| EnvFile
    NuxtConfig -->|docs| ReadmeFile
    NuxtConfig -->|serves assets| PublicDir

    AppVue -->|"login/token exchange (REST)"| SupabaseAuth
    AppVue -->|"CRUD playlists/songs/votes (REST)"| SupabaseDB
    AppVue -->|"subscribe updates (WebSocket)"| SupabaseRealtime
    AppVue -->|"search tracks/get user data (REST)"| SpotifyAPI

    SupabaseRealtime -->|"broadcast updates (WebSocket)"| AppVue

    %% Click Events
    click NuxtConfig "https://github.com/dipstick713/nekomi/blob/main/nuxt.config.ts"
    click AppVue "https://github.com/dipstick713/nekomi/blob/main/app.vue"
    click IndexPage "https://github.com/dipstick713/nekomi/blob/main/pages/index.vue"
    click CreatePage "https://github.com/dipstick713/nekomi/blob/main/pages/create.vue"
    click AddPage "https://github.com/dipstick713/nekomi/blob/main/pages/add.vue"
    click ConfirmPage "https://github.com/dipstick713/nekomi/blob/main/pages/confirm.vue"
    click UserPage "https://github.com/dipstick713/nekomi/blob/main/pages/user.vue"
    click PlaylistPage "https://github.com/dipstick713/nekomi/blob/main/pages/playlist/[id].vue"
    click AddSongComp "https://github.com/dipstick713/nekomi/blob/main/components/AddSong.vue"
    click HeroComp "https://github.com/dipstick713/nekomi/blob/main/components/Hero.vue"
    click LeaderBoardComp "https://github.com/dipstick713/nekomi/blob/main/components/LeaderBoard.vue"
    click PlaylistComp "https://github.com/dipstick713/nekomi/blob/main/components/Playlist.vue"
    click SidebarComp "https://github.com/dipstick713/nekomi/blob/main/components/Sidebar.vue"
    click VoteListComp "https://github.com/dipstick713/nekomi/blob/main/components/VoteList.vue"
    click ComposableUser "https://github.com/dipstick713/nekomi/blob/main/composables/user.ts"
    click MiddlewareAuth "https://github.com/dipstick713/nekomi/blob/main/middleware/auth.ts"
    click EnvFile "https://github.com/dipstick713/nekomi/blob/main/.env.example"
    click ReadmeFile "https://github.com/dipstick713/nekomi/blob/main/README.md"
    click PublicDir "https://github.com/dipstick713/nekomi/tree/main/public/"
    click TsconfigRoot "https://github.com/dipstick713/nekomi/blob/main/tsconfig.json"
    click TsconfigServer "https://github.com/dipstick713/nekomi/blob/main/server/tsconfig.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef backend fill:#D0FFD6,stroke:#238636,color:#000
    classDef external fill:#FFE4B5,stroke:#d69e2e,color:#000
    classDef database fill:#B0E0E6,stroke:#2c7cbf,color:#000
```
