# ben2613/holomusic-pickup-backend architecture

> Architecture diagram of the GitHub repository ben2613/holomusic-pickup-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ben2613/holomusic-pickup-backend
- Repository: https://github.com/ben2613/holomusic-pickup-backend

## Overview

The Hololive Music Pickup Backend is a serverless NestJS application deployed on AWS Lambda. Its primary purpose is to track, filter, and curate Hololive music video releases from YouTube, leveraging several external integrations (DynamoDB, Discord, Holodex API) and scheduled tasks.

##### Main Components
- Serverless Deployment: Highlight AWS Lambda and the Serverless Framework. This is the runtime environment for your NestJS code, deployed using the serverless.yml configuration.
- NestJS Application Structure: Represent the core application entry point (main.ts) and the modular architecture found in src/app. This includes controllers, modules, and services.
- Modules (Components):
- Auth Module – Manages OAuth2 interactions with the YouTube API.
- YouTube Module – Handles YouTube playlist and video data retrieval and processing.
- Holodex Module – Interfaces with the Holodex API for channel data.
- Discord Module – Manages Discord webhook notifications.
- DynamoDB Module – Handles interactions with DynamoDB for song data storage.
- Tasks Module – Contains scheduled tasks including refreshing OAuth tokens and song selection/processing services (song-filter, song-processing, etc.).

##### Relationships and Interactions
- Data Flow: Show how requests from external clients hit health-check and API endpoints (e.g., /auth/oauth/callback, /youtube/playlists). From there, flow is directed to the appropriate controllers and services within the NestJS modules.
- Scheduled Tasks: Illustrate that periodically (daily at specified times) AWS Lambda triggers specific scheduled tasks (checkOAuthToken, fetchAndFilterSongs) within the Tasks module.
- To YouTube API for video/playlist management.
- To Discord webhooks for notifications.
- To the Holodex API for additional Hololive channel data.
- To DynamoDB for persisting song data.
- Internal Module Communication: Represent dependencies, for example, the Tasks module utilizing services from the YouTube, Auth, and DynamoDB modules.

##### Architectural Patterns
- Modular Structure: The use of NestJS modules promotes separation of concerns. Each feature (auth, YouTube, Discord, etc.) has its own module with its controllers and services.
- Serverless Pattern: The entirety of the application runs in a serverless environment (AWS Lambda), emphasizing scalability and managed infrastructure.
- Scheduled Task Handling: Incorporating scheduled tasks as part of your Lambda functions (as seen in serverless.yml & tasks directory) is a key design element.
- Security & Extensibility: OAuth2 integration and proper separation between various API integrations illustrate design principles focusing on secure and maintainable code.

##### Tools, Frameworks, and Technologies
- NestJS – Core framework structuring the backend.
- Serverless Framework – Manages AWS Lambda deployment.
- AWS Lambda – Execution environment.
- DynamoDB – Database for storing song data.
- External APIs: YouTube, Holodex, Discord for respective functionalities.
- Other configurations: Environment variables (from .env.example), Webpack for build configuration, and testing libraries (Jest) for maintaining code quality.

## Diagram (Mermaid)

```mermaid
graph TD
    AWSDeployment["AWS Lambda & Serverless Deployment"]:::aws
    NestCore["NestJS Core Application"]:::nest

    subgraph "NestJS Modules"
        Auth["Auth Module"]:::module
        YouTube["YouTube Module"]:::module
        Holodex["Holodex Module"]:::module
        Discord["Discord Module"]:::module
        Dynamo["DynamoDB Module"]:::module
        Tasks["Tasks Module (Scheduled Tasks)"]:::module
    end

    YT_API["YouTube API"]:::external
    DiscordWebhook["Discord Webhook"]:::external
    HolodexAPI["Holodex API"]:::external
    DynamoDB_DB["DynamoDB Database"]:::external

    AWSDeployment --> NestCore
    NestCore --> Auth
    NestCore --> YouTube
    NestCore --> Holodex
    NestCore --> Discord
    NestCore --> Dynamo
    NestCore --> Tasks

    Tasks -->|"utilizes"| Auth
    Tasks -->|"utilizes"| YouTube
    Tasks -->|"utilizes"| Dynamo

    Auth -->|"calls"| YT_API
    YouTube -->|"calls"| YT_API
    Holodex -->|"calls"| HolodexAPI
    Discord -->|"calls"| DiscordWebhook
    Dynamo -->|"writes_to"| DynamoDB_DB

    click AWSDeployment "https://github.com/ben2613/holomusic-pickup-backend/blob/master/serverless.yml"
    click AWSDeployment "https://github.com/ben2613/holomusic-pickup-backend/blob/master/src/lambda.ts"
    click NestCore "https://github.com/ben2613/holomusic-pickup-backend/blob/master/src/main.ts"
    click NestCore "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app"
    click Auth "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/auth"
    click YouTube "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/youtube"
    click Holodex "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/holodex"
    click Discord "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/discord"
    click Dynamo "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/dynamodb"
    click Tasks "https://github.com/ben2613/holomusic-pickup-backend/tree/master/src/app/modules/tasks"

    classDef aws fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef nest fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;
    classDef module fill:#d6eaf8,stroke:#2874a6,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
```
