# jopedro-labs/core-lib architecture

> Architecture diagram of the GitHub repository jopedro-labs/core-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jopedro-labs/core-lib
- Repository: https://github.com/jopedro-labs/core-lib

## Overview

core-lib is a shared Python support library: callers use its safe file and logging utilities, Google Drive and Discord clients, plus an internal quality-audit agent and a Drive API revision monitor. The Drive client authenticates through OAuth2 before operating on remote files; the monitor separately checks Google's Discovery data and reports results to its execution environment. Several README capabilities are documented but their implementation excerpts were not supplied, so those links are documented rather than inferred from unsampled code.

Main entry points: [`scripts/gdrive_update_bot.py`](https://github.com/jopedro-labs/core-lib/blob/main/scripts/gdrive_update_bot.py) (Drive revision monitor), [`core_lib/gdrive/gdrive_service.py`](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_service.py) (Drive operations), [`core_lib/gdrive/gdrive_helpers.py`](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_helpers.py) (Drive helpers), [`core_lib/discord/discord_service.py`](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/discord/discord_service.py) (Discord notifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_utilities["Core utilities"]
  node_file_utils["Safe file reader<br/>[file_utils.py]"]
  node_logger["Terminal logger<br/>[logger.py]"]
end

subgraph group_integrations["Service integrations"]
  node_gdrive_service["Drive operations<br/>[gdrive_service.py]"]
  node_gdrive_auth["OAuth credentials<br/>[gdrive_auth.py]"]
  node_gdrive_helpers["Drive helpers<br/>[gdrive_helpers.py]"]
  node_discord_service["Discord notifier<br/>[discord_service.py]"]
end

subgraph group_operations["Maintenance tools"]
  node_quality_agent["Quality evaluation agent"]
  node_gdrive_monitor["Drive revision monitor"]
  node_monitor_state["Revision state file"]
end

node_caller(("Library caller"))
node_google_drive{{"Google Drive API"}}
node_discord_api{{"Discord API"}}
node_gemini{{"Gemini AI"}}
node_discovery{{"Google Discovery Service"}}
node_github_actions{{"GitHub Actions"}}

node_caller -->|"reads safely"| node_file_utils
node_caller -->|"logs messages"| node_logger
node_caller -->|"operates files"| node_gdrive_service
node_gdrive_service -->|"gets credentials"| node_gdrive_auth
node_gdrive_service -->|"queries and transfers"| node_google_drive
node_gdrive_helpers -->|"verifies folder"| node_gdrive_service
node_caller -->|"validates folder ID"| node_gdrive_helpers
node_caller -->|"sends notifications"| node_discord_service
node_discord_service -->|"posts messages"| node_discord_api
node_caller -->|"runs audit"| node_quality_agent
node_quality_agent -->|"analyzes quality"| node_gemini
node_caller -->|"runs monitor"| node_gdrive_monitor
node_gdrive_monitor -->|"fetches revisions"| node_discovery
node_gdrive_monitor -->|"loads and saves"| node_monitor_state
node_gdrive_monitor -->|"writes results"| node_github_actions

click node_file_utils "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/file_utils/file_utils.py"
click node_logger "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/logger/logger.py"
click node_gdrive_service "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_service.py"
click node_gdrive_auth "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_auth.py"
click node_gdrive_helpers "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_helpers.py"
click node_discord_service "https://github.com/jopedro-labs/core-lib/blob/main/core_lib/discord/discord_service.py"
click node_quality_agent "https://github.com/jopedro-labs/core-lib/blob/main/scripts/quality_eval_agent.py"
click node_gdrive_monitor "https://github.com/jopedro-labs/core-lib/blob/main/scripts/gdrive_update_bot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_file_utils,node_logger toneBlue
class node_gdrive_service,node_gdrive_auth,node_gdrive_helpers,node_discord_service toneAmber
class node_quality_agent,node_gdrive_monitor,node_monitor_state,node_google_drive,node_discord_api toneMint
class node_caller,node_gemini,node_discovery,node_github_actions toneIndigo
```

## Components

### Core utilities

- [Safe file reader](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/file_utils/file_utils.py): `core_lib/file_utils/file_utils.py`
- [Terminal logger](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/logger/logger.py): `core_lib/logger/logger.py`

### Service integrations

- [Drive operations](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_service.py): `core_lib/gdrive/gdrive_service.py`
- [OAuth credentials](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_auth.py): `core_lib/gdrive/gdrive_auth.py`
- [Drive helpers](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/gdrive/gdrive_helpers.py): `core_lib/gdrive/gdrive_helpers.py`
- [Discord notifier](https://github.com/jopedro-labs/core-lib/blob/main/core_lib/discord/discord_service.py): `core_lib/discord/discord_service.py`

### Maintenance tools

- [Quality evaluation agent](https://github.com/jopedro-labs/core-lib/blob/main/scripts/quality_eval_agent.py): `scripts/quality_eval_agent.py`
- [Drive revision monitor](https://github.com/jopedro-labs/core-lib/blob/main/scripts/gdrive_update_bot.py): `scripts/gdrive_update_bot.py`
- **Revision state file**

### Other components

- **Library caller**
- **Google Drive API**
- **Discord API**
- **Gemini AI**
- **Google Discovery Service**
- **GitHub Actions**

## Connections

- Library caller → Safe file reader: reads safely (evidence: `README.md`)
- Library caller → Terminal logger: logs messages (evidence: `README.md`)
- Library caller → Drive operations: operates files (evidence: `README.md`)
- Drive operations → OAuth credentials: gets credentials (evidence: `core_lib/gdrive/gdrive_service.py`)
- Drive operations → Google Drive API: queries and transfers (evidence: `core_lib/gdrive/gdrive_service.py`)
- Drive helpers → Drive operations: verifies folder (evidence: `core_lib/gdrive/gdrive_helpers.py`)
- Library caller → Drive helpers: validates folder ID (evidence: `README.md`)
- Library caller → Discord notifier: sends notifications (evidence: `README.md`)
- Discord notifier → Discord API: posts messages (evidence: `core_lib/discord/discord_service.py`)
- Library caller → Quality evaluation agent: runs audit (evidence: `README.md`)
- Quality evaluation agent → Gemini AI: analyzes quality (evidence: `README.md`)
- Library caller → Drive revision monitor: runs monitor (evidence: `README.md`)
- Drive revision monitor → Google Discovery Service: fetches revisions (evidence: `scripts/gdrive_update_bot.py`)
- Drive revision monitor → Revision state file: loads and saves (evidence: `scripts/gdrive_update_bot.py`)
- Drive revision monitor → GitHub Actions: writes results (evidence: `scripts/gdrive_update_bot.py`)
