# petter-gao/weread2notion architecture

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

- Interactive diagram: https://gitdiagram.com/petter-gao/weread2notion
- Repository: https://github.com/petter-gao/weread2notion

## Overview

##### Project type and purpose
- This is a small automation tool (not a full‑stack app) whose sole purpose is to “每天定时同步微信读书划线到 Notion” by running a Python script in GitHub Actions.

##### File structure
- Top‐level
- .github/workflows/weread.yml – the CI/CD workflow that schedules and runs the sync
- weread.py – the entry point CLI or main script
- requirements.txt – declares Python dependencies (e.g., requests, notion‑client)
- OUT_FOLDER – local output/cache of fetched highlights (intermediate storage)
- scripts/
– utils.py – helper functions (HTTP clients, parsing, etc.)
– weread.py – core logic for fetching from WeRead and pushing to Notion
- No frontend; purely backend automation.

##### README for additional insights
- Scheduled via GitHub Action (daily)
- Uses WeRead API (via cookies or session) to fetch user highlights/notes
- Uses Notion API to upsert pages under a given Notion database
- Environment variables/secrets drive credentials

a. Main components
1. GitHub Actions Scheduler
2. GitHub Runner (Ubuntu VM)
3. Python Script (weread.py + scripts module)
4. WeRead Service (external HTTP API)
5. Notion Service (external HTTP API)
6. Local Storage (OUT_FOLDER)

b. Relationships / Data flow
1. Scheduler → triggers → Runner
2. Runner → checks out repo → installs dependencies
3. Runner → invokes → Python CLI (weread.py)
4. Python CLI → loads utils + scripts/weread to:
- authenticate & fetch highlights from WeRead API
- compare/store interim results in OUT_FOLDER
- authenticate & push updates to Notion API
5. Notion API → returns status → script logs to Runner console

c. Architectural patterns & principles
- Single responsibility: weread.py is the entrypoint; scripts/weread.py does core sync logic; utils.py holds shared helpers.
- CI/CD as scheduler: using GitHub Actions workflow as a timed cron job.
- Idempotent sync: storing state in OUT_FOLDER to avoid re‑posting duplicates.

d. Key technologies
- GitHub Actions (YAML workflow)
- Python 3.x, pip
- requests or httpx (for REST calls)
- notion‑client or direct REST
- WeRead HTTP endpoints (cookie/session based)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Scheduler["GitHub Actions Scheduler"]:::ci
    Runner["GitHub Runner (Ubuntu VM)"]:::internal
    Secrets["GitHub Secrets (WeRead Cookie, Notion Token, DB ID)"]:::ci
    Requirements["requirements.txt"]:::internal
    OUT["OUT_FOLDER (Local State/Cache)"]:::internal
    WeRead["WeRead Service (HTTP API)"]:::external
    Notion["Notion Service (HTTP API)"]:::external

    subgraph "Python Script"
        Entrypoint["weread.py (CLI Entrypoint)"]:::internal
        CoreLogic["scripts/weread.py (Core Sync Logic)"]:::internal
        Utils["scripts/utils.py (Helper Utilities)"]:::internal
    end

    Scheduler -->|"triggers (daily cron)"| Runner
    Runner -->|"installs deps"| Requirements
    Runner -->|"invokes script"| Entrypoint
    Secrets -->|"env vars"| Entrypoint
    Entrypoint -->|"uses module"| CoreLogic
    Entrypoint -->|"uses module"| Utils
    Entrypoint -->|"read/write state"| OUT
    Entrypoint -->|"fetch highlights"| WeRead
    WeRead -->|"returns data"| Entrypoint
    Entrypoint -->|"push pages"| Notion
    Notion -->|"response status"| Entrypoint

    click Scheduler "https://github.com/petter-gao/weread2notion/blob/main/.github/workflows/weread.yml"
    click Entrypoint "https://github.com/petter-gao/weread2notion/blob/main/weread.py"
    click CoreLogic "https://github.com/petter-gao/weread2notion/blob/main/scripts/weread.py"
    click Utils "https://github.com/petter-gao/weread2notion/blob/main/scripts/utils.py"
    click Requirements "https://github.com/petter-gao/weread2notion/blob/main/requirements.txt"
    click OUT "https://github.com/petter-gao/weread2notion/tree/main/OUT_FOLDER"

    classDef internal fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#186A3B
    classDef ci fill:#FCF3CF,stroke:#F1C40F,color:#B7950B
```
