# itsapurba/kukufm-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/itsapurba/kukufm-downloader
- Repository: https://github.com/itsapurba/kukufm-downloader

## Overview

##### Project type and purpose
- This is a TypeScript-based command-line tool (open-source style utility) whose sole responsibility is to download audio content from KukuFM for personal offline use.
- It orchestrates authentication via custom cookies, batch processing of URLs, HTTP requests to fetch audio files, and writes them to disk.

##### File structure
- Top-level:
- package.json, pnpm-workspace.yaml, pnpm-lock.yaml: project dependencies and workspace config
- tsconfig.json: TypeScript compiler configuration
- README.md, LICENSE, .gitignore: documentation and standard repo files
- src/ directory:
- src/index.ts: the CLI entrypoint (parses args, orchestrates workflow)
- src/cookieUtil.ts: module to read/validate cookies for auth
- src/data/dummyData.ts: placeholder for batch URLs or API response simulation
- src/audio/Dummy Title.mp3: sample output or test asset

##### README for additional insights
- Confirms core features: batch download, custom cookies, flexibility via CLI flags or config files
- Roadmap hints at future REST-API integration, error handling, parallelism, logging

##### Main components and interactions
a. CLI Interface (index.ts)
- Parses user input (URLs, flags)
- Delegates to “Configuration Loader” and “Download Orchestrator”
b. Configuration Loader (could be cookieUtil + future config file)
- Reads src/cookies.json or CLI-passed cookies
- Validates authentication tokens
c. Data Provider
- Currently: dummyData.ts
- Future: HTTP GET from a REST endpoint to retrieve metadata (episode list, URLs)
d. Download Service
- Uses Node’s HTTP/HTTPS or a library (axios/fetch) to stream audio segments
- Applies retry logic, rate limiting (future enhancement)
e. File System Writer
- Streams audio to disk under src/audio/ or configured output directory
f. Types & Schemas
- Type definitions (kukuData, kukuBulkData) enforce compile-time validation of API responses

##### Architectural patterns and design principles
- Modular separation: each concern (CLI, auth, data fetch, file I/O) in its own file
- Dependency inversion: higher-level modules (index.ts) depend on abstractions (cookieUtil interface, typed data)
- Future extensibility: swapping dummyData for a real REST client, adding parallel downloads

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules (blue)
    CLI["CLI / Orchestrator<br>(src/index.ts)"]:::core
    Cookie{"Configuration Loader<br>(Cookie Manager)<br>(src/cookieUtil.ts)"}:::core
    DataProv["Data Provider<br>(Dummy Data)<br>(src/data/dummyData.ts)"]:::core
    Download["Download Service<br>(HTTP Client)<br>(retry & error handling)"]:::core

    %% Configuration & Types (gray)
    Types["Types & Schemas<br>kukuData, kukuBulkData"]:::config

    %% External Interactions (green)
    KukuFM(["KukuFM REST API (Future)"]):::external
    FS(("File System Writer<br>(Output dir: src/audio/)")):::external

    %% Data Flow
    CLI -->|"flags & URLs"| Cookie
    CLI -->|"flags & URLs"| DataProv
    DataProv -->|"EpisodeList (metadata)"| Download
    Download -->|"audio stream"| FS

    %% Future & Annotations
    DataProv -.->|"HTTP GET (future)"| KukuFM
    Types -.-> DataProv

    %% Click Events
    click CLI "https://github.com/itsapurba/kukufm-downloader/blob/main/src/index.ts"
    click Cookie "https://github.com/itsapurba/kukufm-downloader/blob/main/src/cookieUtil.ts"
    click DataProv "https://github.com/itsapurba/kukufm-downloader/blob/main/src/data/dummyData.ts"
    click FS "https://github.com/itsapurba/kukufm-downloader/tree/main/src/audio/"
    click FS "https://github.com/itsapurba/kukufm-downloader/blob/main/src/audio/Dummy Title.mp3"
    click Types "https://github.com/itsapurba/kukufm-downloader/blob/main/src/types/kukuData.d.ts"
    click Types "https://github.com/itsapurba/kukufm-downloader/blob/main/src/types/kukuBulkData.d.ts"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,stroke-width:2px,color:#004D40;
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20;
    classDef config fill:#ECEFF1,stroke:#546E7A,stroke-width:2px,color:#37474F;
```
