# jackyzy823/rajiko architecture

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

- Interactive diagram: https://gitdiagram.com/jackyzy823/rajiko
- Repository: https://github.com/jackyzy823/rajiko

## Overview

##### Project type and purpose
- This is a cross-browser (Chrome/Firefox) extension (Manifest V3) called “Rajiko.”
- Its goal is to bypass geolocation restrictions on Japanese radio streaming services (radiko.jp, NHK, recochoku.jp, etc.), support live recording, timeshift download, and mobile usability.

##### File structure
- Top level:
- manifest.jsonc.tmpl – MV3 manifest template
- background.js – background service worker
- package.py – build/install script
- README.md, LICENSE
- _locales – i18n message catalogs
- Directories:
- modules/ – core logic split by feature: auth.js, recording.js, timeshift.js, rules.js, static.js, util.js
- pages/ – UI HTML & JS: popup.html/js, options.html/js, offscreen.html/js
- ui/ – CSS and injection scripts for specific target sites
- response/ – canned HTML responses for area-free/auth bypass (for local testing or mocks)
- Permissions & APIs in README:
- activeTab, cookies, storage, downloads, scripting, offscreen
- webRequest / declarativeNetRequest / webRequestBlocking
- targets: *.radiko.jp, *.smartstream.ne.jp, *.nhk.jp|or.jp, *.tver.jp, *.recochoku.jp

##### README for additional insights
- Uses a two-step “auth1”/“auth2” handshake mimicking Android app behavior.
- Records HLS/AAC, strips ID3 tags, concatenates segments.
- Offscreen page for Blob URL creation in Chrome.
- Content scripts to inject UI modifications or bypass dialogs on target sites.

##### Components & interactions
1. Browser Extension Host
– Background Service Worker (background.js)
– Offscreen Document (pages/offscreen.html + offscreen.js)
– Popup UI (pages/popup.html + popup.js)
– Options UI (pages/options.html + options.js)
2. Core Logic Modules (modules/*.js)
– auth.js (auth1/auth2 handshake)
– recording.js (live capture pipeline)
– timeshift.js (HLS segment download pipeline)
– rules.js (URL-matching for injection & requests)
– static.js (serve local assets if needed)
– util.js (common helpers)
3. Content Scripts & UI Injectors (ui/*.js, ui/*.css)
4. Storage & State
– chrome.storage.local (settings, token, area config, recording metadata)
5. Browser APIs
– webRequest / declarativeNetRequest (modify headers, bypass geo)
– downloads.download (save blob to local)
– cookies API (force area cookie)
– offscreen (AudioBlob creation in Chrome)
6. External Services
– Radiko API endpoints (auth1/auth2, HLS m3u8, AAC segments)
– Smartstream / radiko-cf.com (media storage)
– NHK / recochoku / tver (bonus streams)

- Background → loads modules/auth → issues auth1 request → receives token/keys → modules/auth → auth2 request → obtains location-validated session
- Background → modules/recording or modules/timeshift → requests HLS manifest + TS/AAC segments → pipes data to Offscreen page (or directly to downloads API)
- Offscreen page → constructs Blob URL → triggers downloads.download
- Background / Content Scripts → apply rules.js → intercept or inject requests/responses → bypass geo-checks
- Background → chrome.storage to read/write user settings (area, credentials)
- Content Scripts → ui/*.js & .css → modify target pages (e.g., TVer, Recochoku)

c. Architectural patterns & principles:
- Modular separation of concerns: authentication, recording, UI, utilities
- Event-driven background service worker responds to messages & browser triggers
- Use of offscreen document as worker for heavy binary processing
- DeclarativeNetRequest/webRequestBlocking pattern for request rewriting

d. Key technologies:
- JavaScript ES modules (in modules/*)
- Chrome MV3 APIs: service worker, offscreen, downloads, storage, webRequest
- i18n with _locales
- HLS streaming (ID3 tag stripping, AAC_ADTS concatenation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Extension Components
    subgraph "Extension Components"
        BSW["Background Service Worker"]:::extension
        OS["Offscreen Document"]:::extension
        PU["Popup UI"]:::extension
        OU["Options UI"]:::extension
        MF["Manifest Template"]:::extension
    end

    %% Core Logic Modules
    subgraph "Core Logic Modules"
        AUTH["Auth Module"]:::extension
        REC["Recording Module"]:::extension
        TSM["Timeshift Module"]:::extension
        RUL["Rules Module"]:::extension
        STA["Static Module"]:::extension
        UTL["Util Module"]:::extension
    end

    %% Content Scripts & UI Injectors
    subgraph "Content Scripts & UI Injectors"
        CS["Content Scripts & UI Injectors"]:::extension
    end

    %% Localization Catalogs
    subgraph "Localization Catalogs"
        LOC["_locales"]:::extension
    end

    %% Mock Response Templates
    subgraph "Mock Response Templates"
        MCK["response/"]:::extension
    end

    %% Build Script
    Package["Build/Install Script"]:::extension

    %% Browser APIs
    subgraph "Browser APIs"
        WR["webRequest / dNR"]:::api
        DL["downloads.download"]:::api
        CK["cookies API"]:::api
        ST["chrome.storage.local"]:::storage
        OSAPI["offscreen API"]:::api
    end

    %% External Services
    subgraph "External Services"
        RadikoAPI["Radiko API"]:::external
        Smart["Smartstream / radiko-cf.com"]:::external
        NHK["NHK / recochoku / tver"]:::external
    end

    %% User Interaction
    User["User"]:::external -->|click extension icon| PU
    PU -->|"invoke"| BSW
    OU -->|"invoke"| BSW

    %% Background interactions
    BSW -->|loads| AUTH
    BSW -->|loads| REC
    BSW -->|loads| TSM
    BSW -->|loads| RUL
    BSW -->|loads| STA
    BSW -->|loads| UTL
    BSW -->|triggers| OS
    BSW -->|uses| CS
    BSW -->|reads/writes| LOC
    BSW -->|reads/writes| MCK
    Package -->|builds| MF

    %% Core modules to APIs and Offscreen
    AUTH -->|"auth1/auth2 requests"| RadikoAPI
    REC -->|"live capture"| OS
    REC -->|pipe Blob| DL
    TSM -->|"HLS segments"| OS
    TSM -->|pipe Blob| DL
    RUL -->|"intercept requests"| WR
    STA -->|"serve mocks"| MCK
    UTL -->|helpers| BSW

    %% Background to Browser APIs
    BSW -->|modify headers| WR
    BSW -->|download blob| DL
    BSW -->|set cookies| CK
    BSW -->|store data| ST
    BSW -->|spawn offscreen| OSAPI

    %% External services access
    REC --> RadikoAPI
    TSM --> RadikoAPI
    AUTH --> RadikoAPI
    REC --> Smart
    TSM --> NHK

    %% Styling
    classDef extension fill:#cdeaff,stroke:#0366d6,color:#0366d6;
    classDef api fill:#d4f8d4,stroke:#1a7f37,color:#1a7f37;
    classDef external fill:#ffe4b5,stroke:#d97904,color:#d97904;
    classDef storage fill:#f0f0f0,stroke:#999999,color:#333333;

    %% Click Events
    click BSW "https://github.com/jackyzy823/rajiko/blob/master/background.js"
    click OS "https://github.com/jackyzy823/rajiko/blob/master/pages/offscreen.html"
    click PU "https://github.com/jackyzy823/rajiko/blob/master/pages/popup.html"
    click OU "https://github.com/jackyzy823/rajiko/blob/master/pages/options.html"
    click MF "https://github.com/jackyzy823/rajiko/blob/master/manifest.jsonc.tmpl"
    click AUTH "https://github.com/jackyzy823/rajiko/blob/master/modules/auth.js"
    click REC "https://github.com/jackyzy823/rajiko/blob/master/modules/recording.js"
    click TSM "https://github.com/jackyzy823/rajiko/blob/master/modules/timeshift.js"
    click RUL "https://github.com/jackyzy823/rajiko/blob/master/modules/rules.js"
    click STA "https://github.com/jackyzy823/rajiko/blob/master/modules/static.js"
    click UTL "https://github.com/jackyzy823/rajiko/blob/master/modules/util.js"
    click CS "https://github.com/jackyzy823/rajiko/tree/master/ui/"
    click LOC "https://github.com/jackyzy823/rajiko/tree/master/_locales/"
    click MCK "https://github.com/jackyzy823/rajiko/tree/master/response/"
    click Package "https://github.com/jackyzy823/rajiko/blob/master/package.py"
```
