# yesinkim/schedule-ninja architecture

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

- Interactive diagram: https://gitdiagram.com/yesinkim/schedule-ninja
- Repository: https://github.com/yesinkim/schedule-ninja

## Overview

##### Main Components
- Browser Host (Google Chrome)
- Extension contexts: Content Script, Background Service Worker, Popup UI
- On-Device AI Module
- Gemini Nano (local model)
- External AI APIs (Prompt, Summarizer, Proofreader, Translator [planned])
- Google Calendar API
- UI Assets & Localization
- _locales messages

##### Relationships & Data Flows
a. User Action → Content Script
- “Drag” or “right-click” selection
- Content Script (`content.js`) observes DOM, captures context, injects inline modal
b. Content Script ↔ Background Worker
- chrome.runtime.sendMessage: send structured context
- Background Service Worker (`background.js`) receives, orchestrates AI calls
c. Background Worker → On-Device AI & External APIs
- First route: Gemini Nano for core parsing
- Fallback/secondary: Prompt API → Summarizer API → Proofreader API
d. Background Worker → Popup UI
- Pre-filled event draft pushed to `popup.html`/`popup.js`
e. User Confirmation in Popup → Background Worker → Google Calendar API
- Final event creation
f. Activity Log (in‐extension storage)
- Recent actions stored locally and displayed in Popup

##### Architectural Patterns
- MV3 Extension Pattern (manifest.json defines entry points, permissions)
- Event-driven, message-passing between contexts
- Separation of concerns:
- content.js for page interactions
- background.js for orchestration & external calls
- popup.js for user review
- Privacy-first: on-device inference (Gemini Nano) before external calls

##### Incorporate Technologies & Configurations
- manifest.json (MV3 config, permissions: storage, contextMenus, identity, scripting)
- content.js: DOM observation, inline modal injection
- background.js: chrome.alarms, chrome.identity, fetch to Google Calendar
- popup.html/css/modal.css/popup.js: React-like or vanilla JS UI
- _locales for i18n
- secrets.example.js (placeholder for API keys)

##### Putting It All Together
- Top-layer: Chrome Browser
- Middle-layer: On-Device AI Module (Gemini Nano)
- Side-layer: External AI Services (Prompt, Summarizer, Proofreader)
- Bottom-layer: Google Calendar API
- Storage: Local extension storage (activity log) attached to Background & Popup

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser Host (Chrome)"
        CS["Content Script"]:::ext
        BG["Background Service Worker"]:::ext
        subgraph "Popup UI"
            PH["popup.html"]:::ext
            PJ["popup.js"]:::ext
            CSS["css/modal.css"]:::config
        end
    end

    MF["manifest.json"]:::config
    SE["secrets.example.js"]:::config

    subgraph "Localization (_locales)"
        EMSG["_locales/en/messages.json"]:::config
        KMSG["_locales/ko/messages.json"]:::config
    end

    ICONS["icons/"]:::config

    GN["Gemini Nano\n(On-Device AI)"]:::ai

    subgraph "External AI Services"
        P1["Prompt API"]:::external
        S1["Summarizer API"]:::external
        PR["Proofreader API"]:::external
    end

    GC["Google Calendar API"]:::calendar

    DB[(Activity Log)]:::storage

    %% Connections
    CS -->|"chrome.runtime.sendMessage: context"| BG
    BG -->|"local inference"| GN
    BG -->|"HTTP API call"| P1
    P1 -->|"response"| BG
    BG -->|"HTTP API call"| S1
    S1 -->|"response"| BG
    BG -->|"HTTP API call"| PR
    PR -->|"response"| BG
    BG -->|"OAuth + REST /events.insert"| GC
    BG -->|"store action"| DB
    BG -->|"push draft"| PH
    PH -->|"read log"| DB
    CS -->|"inject inline modal"| PH

    %% Config relationships
    MF -.-> CS
    MF -.-> BG
    MF -.-> PH

    SE -.-> BG

    ICONS -.-> CS
    ICONS -.-> PH

    EMSG -.-> PH
    KMSG -.-> PH

    %% Click Events
    click CS "https://github.com/yesinkim/schedule-ninja/blob/main/content.js"
    click BG "https://github.com/yesinkim/schedule-ninja/blob/main/background.js"
    click PH "https://github.com/yesinkim/schedule-ninja/blob/main/popup.html"
    click PJ "https://github.com/yesinkim/schedule-ninja/blob/main/popup.js"
    click CSS "https://github.com/yesinkim/schedule-ninja/blob/main/css/modal.css"
    click MF "https://github.com/yesinkim/schedule-ninja/blob/main/manifest.json"
    click EMSG "https://github.com/yesinkim/schedule-ninja/blob/main/_locales/en/messages.json"
    click KMSG "https://github.com/yesinkim/schedule-ninja/blob/main/_locales/ko/messages.json"
    click ICONS "https://github.com/yesinkim/schedule-ninja/tree/main/icons/"
    click SE "https://github.com/yesinkim/schedule-ninja/blob/main/secrets.example.js"
    click README1 "https://github.com/yesinkim/schedule-ninja/blob/main/README.md"
    click README2 "https://github.com/yesinkim/schedule-ninja/blob/main/README.ko.md"

    %% Documentation
    subgraph "Documentation"
        README1["README.md"]:::config
        README2["README.ko.md"]:::config
    end

    %% Styles
    classDef ext fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ai fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef calendar fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef storage fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef config fill:#e8e8e8,stroke:#333,stroke-width:1px
```
