# khmuhtadin/metosheet architecture

> Architecture diagram of the GitHub repository khmuhtadin/metosheet, 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/khmuhtadin/metosheet
- Repository: https://github.com/khmuhtadin/metosheet

## Overview

##### Main components of the system
a. Application Core Modules:
- main.py: The primary entry point that handles Facebook Ads data fetching, processing, and synchronization with Google Sheets.
- billing.py: A separate module used specifically for processing and tracking billing transactions, including VAT calculations and invoice URL generation.

b. Configuration and Environment:
- .env and .env.example: Files that store critical credentials and configuration details for accessing the Facebook Marketing API and Google Sheets API.
- requirements.txt: Lists the Python dependencies required, indicating the libraries and frameworks (such as gspread for Google Sheets integration) that support the application.

c. External Services and APIs:
- Facebook Marketing API: The source of the Facebook Ads data including campaign metrics (impressions, spend, clicks, etc.).
- Google Sheets API: Destination where data gets synchronized on a daily basis.

d. Automation and CI/CD:
- GitHub Actions workflows (in .github/workflows folder): Automated daily synchronization (triggered at 08:00 GMT+7). This setup ensures the synchronization tasks are scheduled and can be triggered manually if needed.

e. Documentation:
- docs/ directory: Contains assets (like images) and additional documentation that supports understanding and maintaining the system.

##### Architectural patterns and design principles
- The project follows a modular design where separate scripts serve distinct responsibilities (data collection vs. billing processing).
- Clear decoupling between configuration (environment variables) and logic, improving maintainability and security.
- Use of automation (CI/CD via GitHub Actions) indicates a pattern for continuous integration and scheduled tasks, ensuring data is regularly updated.

##### Specific elements
- Clearly labeled components: “main.py”, “billing.py”, “Configuration (.env)”, “GitHub Actions Workflow”, “Facebook Marketing API”, “Google Sheets API”, and “Documentation”.
- Labels and brief descriptions where possible, such as “Automated Daily Sync” next to the GitHub Actions component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        CONFIG["Configuration (.env)"] 
        DEP["Dependencies (requirements.txt)"]
    end

    AUTOMATION["GitHub Actions Workflow<br>(Automated Daily Sync)"]
    DOC["Documentation"]

    subgraph "Application Core"
        MAIN["main.py"]
        BILL["billing.py"]
    end

    EX_FB["((Facebook Marketing API))"]
    EX_GS["((Google Sheets API))"]

    CONFIG --> MAIN
    CONFIG --> BILL
    AUTOMATION --> MAIN
    MAIN -->|"fetch"| EX_FB
    MAIN -->|"upload"| EX_GS
    BILL -->|"billing"| EX_FB
    BILL -->|"billing_sync"| EX_GS

    %% Click Events
    click MAIN "https://github.com/khmuhtadin/metosheet/blob/main/main.py"
    click BILL "https://github.com/khmuhtadin/metosheet/blob/main/billing.py"
    click CONFIG "https://github.com/khmuhtadin/metosheet/blob/main/.env.example"
    click DEP "https://github.com/khmuhtadin/metosheet/blob/main/requirements.txt"
    click AUTOMATION "https://github.com/khmuhtadin/metosheet/blob/main/.github/workflows/daily-sync.yml"
    click DOC "https://github.com/khmuhtadin/metosheet/tree/main/docs/"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef config fill:#FFF7BA,stroke:#333,stroke-width:2px;
    classDef automation fill:#BAFFC9,stroke:#333,stroke-width:2px;
    classDef external fill:#FFDFBA,stroke:#333,stroke-width:2px;
    class MAIN,BILL internal;
    class CONFIG,DEP config;
    class AUTOMATION automation;
    class EX_FB,EX_GS external;
    class DOC config;
```
