# muraseryosuke/murase-dosei architecture

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

- Interactive diagram: https://gitdiagram.com/muraseryosuke/murase-dosei
- Repository: https://github.com/muraseryosuke/murase-dosei

## Overview

##### Project type and purpose
- This is a serverless, static-site web application that aggregates personal online activities into a single timeline.
- It uses GitHub Pages for hosting, GitHub Actions for automation, and a single JSON file (`timeline.json`) in the repo as its data store.

##### File structure
- Top level:
- `.github/workflows/fetch.yml` – scheduled CI workflow to fetch new data
- `scripts/fetch_activities.js` – Node script that calls external APIs and updates `timeline.json`
- `timeline.json` – the canonical timeline data stored in the repo
- `index.html` – the single-page frontend that reads `timeline.json` and renders the timeline
- `package.json` – project metadata, dev dependencies (e.g., for the fetch script)
- There are no backend servers or databases; everything runs as scheduled jobs and static assets.

##### README for additional insights
- Workflow steps: schedule → fetch from Spotify API → commit JSON → GitHub Pages deploy
- Frontend loads and groups events by date, supports infinite scroll and dark mode
- Entire stack: vanilla HTML/CSS/JS + GitHub Actions + GitHub Pages

##### Main components and interactions
a. External Services
- Spotify API (future: other services)
b. Automation Pipeline
- GitHub Actions scheduler (defined in `fetch.yml`)
- `scripts/fetch_activities.js` (runs under Node.js)
- Commits updated `timeline.json` back to the repository
c. Data Store
- `timeline.json` in the Git repo acts as the persistent store
d. Hosting
- GitHub Pages serves static assets (`index.html` + JS + CSS + `timeline.json`)
e. Client
- User’s browser loads `index.html`, fetches `timeline.json`, renders the UI

##### Relationships and data flow
1. Scheduler triggers GitHub Actions at configured intervals.
2. Action runs `fetch_activities.js`, which:
– Reads existing `timeline.json` from the repo
– Calls Spotify API, merges new activity data
– Writes back to `timeline.json` and commits to the repo
3. Repo changes auto-deploy to GitHub Pages.
4. End users navigate to the site; browser:
– Downloads `index.html` and supporting JS/CSS
– Fetches `timeline.json` via HTTP
– Dynamically renders grouped events with infinite scroll

##### Architectural patterns and principles
- Serverless / CI-driven data ingestion
- Static-site single-page application
- Git as both source control and data store
- Clear separation: automation layer vs. frontend layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Automation Layer
    subgraph "Automation Layer"
        style AutomationLayer fill:none,stroke:none
        Scheduler["Scheduler<br>(GitHub Actions)"]:::automation
        Fetch["Fetch Script<br>(fetch_activities.js)"]:::automation
    end

    %% External Services
    ExtAPI["Spotify API"]:::external

    %% Data Store
    Repo["Git Repo /<br>timeline.json"]:::datastore

    %% Hosting
    Pages["GitHub Pages"]:::hosting

    %% Client Layer
    subgraph "Client"
        Browser["Client Browser"]:::client
        Index["index.html<br>(SPA)"]:::client
    end

    %% Project Configuration
    subgraph "Project Files"
        Package["package.json"]:::code
        DirCI[".github/workflows/"]:::code
        DirScripts["scripts/"]:::code
    end

    %% Relationships
    Scheduler -->|"triggers"| Fetch
    Fetch -->|"reads timeline.json"| Repo
    Fetch -->|"fetches data"| ExtAPI
    ExtAPI -->|"returns data"| Fetch
    Fetch -->|"commits update"| Repo
    Repo -->|"auto-deploy"| Pages
    Browser -->|"HTTP GET index.html"| Pages
    Browser -->|"HTTP GET timeline.json"| Pages
    Browser -->|"renders UI"| Index
    Package -->|"provides dependencies"| Fetch

    %% Click Events
    click Scheduler "https://github.com/muraseryosuke/murase-dosei/blob/main/.github/workflows/fetch.yml"
    click Fetch "https://github.com/muraseryosuke/murase-dosei/blob/main/scripts/fetch_activities.js"
    click Repo "https://github.com/muraseryosuke/murase-dosei/blob/main/timeline.json"
    click Index "https://github.com/muraseryosuke/murase-dosei/blob/main/index.html"
    click Package "https://github.com/muraseryosuke/murase-dosei/blob/main/package.json"
    click DirCI "https://github.com/muraseryosuke/murase-dosei/tree/main/.github/workflows/"
    click DirScripts "https://github.com/muraseryosuke/murase-dosei/tree/main/scripts/"

    %% Styles
    classDef automation fill:#f9a825,stroke:#333,stroke-width:1px,color:#000
    classDef datastore fill:#42a5f5,stroke:#333,stroke-width:1px,color:#fff
    classDef hosting fill:#66bb6a,stroke:#333,stroke-width:1px,color:#000
    classDef client fill:#ab47bc,stroke:#333,stroke-width:1px,color:#fff
    classDef code fill:#90a4ae,stroke:#333,stroke-width:1px,color:#000
    classDef external fill:#b0bec5,stroke:#333,stroke-width:1px,color:#000
```
