# malinkang/weread2notion-pro architecture

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

- Interactive diagram: https://gitdiagram.com/malinkang/weread2notion-pro
- Repository: https://github.com/malinkang/weread2notion-pro

## Overview

##### Project Type & Purpose
- This project is a specialized utility tool that automates the synchronization of reading highlights and notes from WeChat Reading (“微信读书”) into Notion.
- It is implemented in Python and utilizes GitHub Actions to schedule the synchronization tasks daily.
- The README confirms that the tool is intended to help users automatically bridge content between WeChat Reading and Notion.

##### Analyzing the File Structure
- Top-Level Files & Directories:
- .github/workflows: Contains GitHub Action configuration files (read_time.yml and weread.yml). These files define scheduled workflows that trigger the synchronization process.
- __main__.py: Likely the entry point when the package is executed.
- config.py: Responsible for handling configuration, which could include API keys, endpoints, and other settings.
- book.py: Likely contains logic to represent or parse book-related data.
- notion_helper.py: Provides helper functions and integration with the Notion API.
- read_time.py and weread.py: These modules probably handle reading data/process interactions with WeChat Reading.
- weread_api.py: Likely contains helpers or wrappers for interacting with the WeChat Reading API.
- utils.py: Contains utility functions used across the project.
- Additional Files:
- requirements.txt: Lists required Python packages.
- setup.py: Used to install or distribute the package.
- README.md: Offers usage instructions, project description, and social links.
- asset/OUT_FOLDER: Could be holding generated outputs/images or temporary data.

##### Core Components and Their Roles
- GitHub Actions Workflows:
- Two workflow files (read_time.yml and weread.yml) schedule and trigger the sync process.
- Application Core:
- The Python package “weread2notionpro” acts as the main processing engine.
- Within it, different modules handle integration points (WeChat Reading API, Notion API) and data processing.
- WeChat Reading Integration:
- Modules like weread.py and weread_api.py are in charge of connecting to, fetching, and processing data from WeChat Reading.
- Notion Integration:
- The notion_helper.py module encapsulates the logic necessary for pushing the highlights/notes to Notion.
- Configuration & Utility:
- config.py sets up the environment (e.g., API keys, endpoints), while utils.py provides supporting functions.
- Data Handling:
- book.py and read_time.py are likely involved in managing the book content and its reading time metrics.

##### Relationships & Interactions
- GitHub Actions trigger the scheduled runs that invoke the entry point (__main__.py) of the weread2notionpro package.
- The __main__.py module orchestrates calls to:
- A module that interacts with WeChat Reading (weread_api and/or weread) to pull the latest highlights and notes.
- Processing logic that might use book.py, read_time.py, and utils.py to massage the data.
- The notion_helper.py module, which takes processed data and updates the Notion workspace.
- The config.py module interlinks these processes by providing the necessary configuration and credentials.
- External APIs: WeChat Reading’s service (to retrieve data) and the Notion API (to update content).

##### Architectural Patterns & Design Principles
- Modular Design: Each component (configuration, API integration, processing) is separated into its own module.
- Separation of Concerns: GitHub Actions are used solely for scheduling, while the Python package does all the business logic.
- Extensibility: The clear division into different functionalities (e.g., handling WeChat Reading vs. Notion interactions) suggests that the system can be easily maintained or extended—perhaps to support additional services.
- Automated Deployment: Integration with GitHub Actions indicates an emphasis on automation and continuous operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub Actions Scheduler
    subgraph "GitHub Actions Scheduler"
        A1("Read Time Workflow"):::github
        A2("WeRead Workflow"):::github
    end

    %% Application Core
    subgraph "Application Core (weread2notionpro)"
        B1("__main__.py"):::core
        B2("Configuration Utility (config.py)"):::config
        B3("WeChat Reading Integration (weread.py)"):::core
        B4("WeChat Reading API Wrapper (weread_api.py)"):::core
        B5("Notion API Helper (notion_helper.py)"):::core
        B6("Book Data Handler (book.py)"):::core
        B7("Read Time Processing (read_time.py)"):::core
        B8("Utility Functions (utils.py)"):::utils
    end

    %% Supporting Files
    subgraph "Supporting Files"
        C1("requirements.txt & setup.py"):::config
    end

    %% External Services
    subgraph "External Services"
        D1("WeChat Reading Service"):::external
        D2("Notion API"):::external
    end

    %% Connections from GitHub Actions to Entry Point
    A1 -->|"triggers"| B1
    A2 -->|"triggers"| B1

    %% Configuration flows
    B2 -->|"provides_config"| B1
    B2 -->|"config"| B3
    B2 -->|"config"| B4
    B2 -->|"config"| B5

    %% Main orchestration in Entry Point
    B1 -->|"fetches_data"| B3
    B1 -->|"fetches_data"| B4
    B1 -->|"processes_data"| B6
    B1 -->|"processes_data"| B7
    B1 -->|"updates"| B5
    B1 -->|"uses"| B8

    %% External API calls
    B3 -->|"calls"| D1
    B4 -->|"calls"| D1
    B5 -->|"pushes_data"| D2

    %% Class definitions for styling
    classDef github fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef utils fill:#e6ccff,stroke:#9933ff,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#b38600,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/malinkang/weread2notion-pro/blob/main/.github/workflows/read_time.yml"
    click A2 "https://github.com/malinkang/weread2notion-pro/blob/main/.github/workflows/weread.yml"
    click B1 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/__main__.py"
    click B2 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/config.py"
    click B3 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/weread.py"
    click B4 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/weread_api.py"
    click B5 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/notion_helper.py"
    click B6 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/book.py"
    click B7 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/read_time.py"
    click B8 "https://github.com/malinkang/weread2notion-pro/blob/main/weread2notionpro/utils.py"
```
