# npjigak/twitch-follower-checker architecture

> Architecture diagram of the GitHub repository npjigak/twitch-follower-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/npjigak/twitch-follower-checker
- Repository: https://github.com/npjigak/twitch-follower-checker

## Overview

##### Project type and purpose
- This is a client-centric, multi-language, static/SSR web application built with Next.js and MDX for localized content.
- Its core feature is a browser-based interface that authenticates a streamer via OAuth, polls the Twitch API for follower changes, and displays new followers and unfollowers in real time.

##### File structure
- **pages/** – Next.js routing for static and dynamic content, organized by locale (e.g., pages/en, pages/ja), plus MDX files for documentation pages.
- **components/** – React UI pieces (AppContainer, AuthenticateWithTwitch, RefreshListsButton, etc.).
- **lib/** – Utility modules:
- accessTwitch.ts – wrapper for Twitch HTTP API calls
- countdownWorker.ts – a Web Worker for countdown timers
- gtm.ts – Google Tag Manager integration
- debugLogger.ts, constants.ts, navigateToUserLocalePage.tsx
- **next.config.mjs**, **postcss.config.js**, **tailwind.config.ts** – build and styling configuration.
- **.github/workflows/** – CI/CD pipelines: Next.js build/deploy, IndexNow sitemap updates.
- **public/** – static assets (if any) served by Next.js.

##### README for additional insights
- It confirms the user-facing purpose (tracking followers/unfollowers) and points to multi-locale documentation.
- No backend microservice; all dynamic logic runs in the browser or at build time (SSG/ISR).

##### Main architectural components (to represent
A. End User (Browser)
- Interacts with the Next.js React SPA/SSR pages.
- Hosts the Web Worker for countdowns.
B. Next.js Framework / Hosting
- SSR/SSG server (Vercel, Netlify or similar CDN).
- Serves static HTML, JS bundles, generated MDX content.
- Runs getStaticProps / getServerSideProps at build or request time (if used).
C. CI/CD Pipeline
- GitHub Actions workflows triggered on push.
- Runs linting, builds the Next.js app, generates sitemap, and deploys to hosting.
D. External Services
- Twitch API (OAuth2 token acquisition + follower data endpoints).
- Google Tag Manager (for analytics).
- IndexNow (for sitemap submission).

##### Relationships and data flows
1. User navigates to the site (DNS → CDN → Next.js app).
2. AppContainer loads, picks correct locale, and renders MDX pages + React UI.
3. User clicks “Authenticate with Twitch” → OAuth popup → Twitch Authorization Server → redirect with token.
4. accessTwitch module uses the token to call Twitch’s follower endpoints periodically (polling or via countdownWorker).
5. Data is displayed in the UI; debugLogger writes to console if enabled.
6. gtm module fires analytics events.

##### Architectural patterns & principles
- **Client-centric rendering** with optional SSR/SSG for SEO and multi-locale docs.
- **Separation of concerns:**
- UI components in components/
- API integration in lib/
- Configuration in root config files.
- **CD pipeline** for automated builds, tests, sitemap updates, and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User Flow
    User["End User (Browser)"]:::external
    subgraph "Browser (Client)"
        direction TB
        UI["React UI Components"]:::internal
        Worker["Countdown Web Worker"]:::internal
    end
    User -->|"navigate to site"| CDN["CDN (Vercel/Netlify)"]:::external
    CDN -->|"serve HTML/JS"| NextJS["Next.js (SSR/SSG)"]:::internal
    NextJS --> UI
    UI -->|"spawn"| Worker

    %% Authentication & Twitch API
    UI -->|"OAuth2 flow"| TwitchAuth["Twitch Authorization Server"]:::external
    TwitchAuth -->|"redirect with token"| UI
    UI -->|"GET /followers"| AccessTwitch["accessTwitch Module"]:::internal
    AccessTwitch -->|"calls endpoints"| TwitchAPI["Twitch API"]:::external
    Worker -->|"poll interval"| AccessTwitch
    UI -->|"analytics event"| GTM["Google Tag Manager"]:::external
    UI -->|"log debug"| DebugLogger["Debug Logger"]:::internal

    %% Static Assets
    Static["Public Assets"]:::static
    NextJS --> Static

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GitPush["git push trigger"]:::ci
        Actions["GitHub Actions"]:::ci
        Sitemap["IndexNow Sitemap Update"]:::ci
        Build["Next.js Build & Deploy"]:::ci
    end
    GitPush --> Actions
    Actions --> Build
    Actions --> Sitemap
    Build --> CDN

    %% File Structure Containers
    subgraph "Pages & Localization"
        direction TB
        Pages["pages/"]:::internal
    end

    subgraph "Components"
        direction TB
        Components["components/"]:::internal
    end

    subgraph "Libraries"
        direction TB
        AccessTwitch
        Worker
        GTM
        DebugLogger
        NavLocale["Locale Navigation Utility"]:::internal
        Constants["Constants Definition"]:::internal
    end

    subgraph "Configuration"
        direction TB
        NextConfig["next.config.mjs"]:::internal
        PostCSS["postcss.config.js"]:::internal
        Tailwind["tailwind.config.ts"]:::internal
        Theme["theme.config.tsx"]:::internal
        TSConfig["tsconfig.json"]:::internal
        Eslint[".eslintrc.json"]:::internal
        PackageJSON["package.json"]:::internal
        Readme["README.md"]:::internal
    end

    subgraph "CI/CD Config"
        direction TB
        NextYML[".github/workflows/nextjs.yml"]:::ci
        IndexNowYML[".github/workflows/IndexNow.yml"]:::ci
    end

    %% Click Events
    click Pages "https://github.com/npjigak/twitch-follower-checker/tree/main/pages/"
    click Components "https://github.com/npjigak/twitch-follower-checker/tree/main/components/"
    click AccessTwitch "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/accessTwitch.ts"
    click Worker "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/countdownWorker.ts"
    click GTM "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/gtm.ts"
    click DebugLogger "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/debugLogger.ts"
    click NavLocale "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/navigateToUserLocalePage.tsx"
    click Constants "https://github.com/npjigak/twitch-follower-checker/blob/main/lib/constants.ts"
    click NextConfig "https://github.com/npjigak/twitch-follower-checker/blob/main/next.config.mjs"
    click PostCSS "https://github.com/npjigak/twitch-follower-checker/blob/main/postcss.config.js"
    click Tailwind "https://github.com/npjigak/twitch-follower-checker/blob/main/tailwind.config.ts"
    click Theme "https://github.com/npjigak/twitch-follower-checker/blob/main/theme.config.tsx"
    click TSConfig "https://github.com/npjigak/twitch-follower-checker/blob/main/tsconfig.json"
    click Eslint "https://github.com/npjigak/twitch-follower-checker/blob/main/.eslintrc.json"
    click PackageJSON "https://github.com/npjigak/twitch-follower-checker/blob/main/package.json"
    click Readme "https://github.com/npjigak/twitch-follower-checker/blob/main/README.md"
    click NextYML "https://github.com/npjigak/twitch-follower-checker/blob/main/.github/workflows/nextjs.yml"
    click IndexNowYML "https://github.com/npjigak/twitch-follower-checker/blob/main/.github/workflows/IndexNow.yml"
    click Static "https://github.com/npjigak/twitch-follower-checker/tree/main/public/"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#E6FFED,stroke:#28a745,color:#28a745
    classDef ci fill:#FFF5E6,stroke:#D97706,color:#D97706
    classDef static fill:#F2F2F2,stroke:#666666,color:#666666
```
