# 0yeifer/any_calendar architecture

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

- Interactive diagram: https://gitdiagram.com/0yeifer/any_calendar
- Repository: https://github.com/0yeifer/any_calendar

## Overview

##### Project type and purpose
- This is a Frappe‐based plugin/app (“extended_calendars”) whose goal is to integrate and sync events between two external calendar providers (GoHighLevel and HubSpot) and the native Frappe/ERPNext calendar.
- It uses Frappe’s MVC architecture: Python “doctype” classes for server logic and persistence, JSON files for metadata, JS files for client UI, hooks for extension points, and patch scripts for migrations.

##### Main components
a. Frappe Framework (Core)
– HTTP/TCP server (Bench)
– Web client (Desk UI)
– REST API / RPC layer
– ORM + MariaDB (or PostgreSQL) backing store
b. extended_calendars App
– Python doctype modules: calendar_hubspot, ghl_calendar, goujana_calendar
– JSON doctype definitions (schema + permissions)
– JS extension files for client‐side override/customization
– hooks.py (to register scheduled tasks, API overrides, event handlers)
– patches (migration scripts)
– overrides for built‐in doctypes (contact, event, google_calendar)
c. External Calendar Providers
– HubSpot Calendar API
– GoHighLevel Calendar API
d. Users & Clients
– Browser/Desk users interacting via UI
– Scheduled Jobs or Webhooks (for sync logic)

##### Relationships & Data Flow
1. User (browser) → Frappe Desk UI (JS) → Frappe REST/RPC → Python doctype controllers → Database
2. Sync job (hooked scheduler or webhook) → Python integration logic → external API (HubSpot/GoHighLevel) ↔ HTTP ↔ Frappe doctype records
3. Overrides intercept CRUD on core “Event”/“Contact” doctypes to propagate changes bidirectionally.
4. Patch scripts run at app installation to migrate existing calendars.

##### Architectural Patterns & Principles
- MVC (Model = Doctypes/ORM, View = Frappe Desk JS templates, Controller = Python methods + hooks)
- Plugin/Hook architecture (app extends core without modifying core code)
- Adapter pattern for external APIs (calendar_hubspot.py, ghl_calendar.py each wrap provider REST calls)
- Separation of concerns:
- Data model in JSON/Python
- Sync logic in Python modules
- UI tweaks in JS override files

##### Technologies & Frameworks
- Python 3.x, Frappe framework
- MariaDB (or PostgreSQL)
- JSON (metadata definitions)
- JavaScript (client overrides in public/js)
- pyproject.toml for packaging
- CI via GitHub Actions (.github/workflows/ci.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users & Clients
    subgraph "Users & Clients"
        User["Browser / Desk UI"]:::users
    end

    %% Frappe Core
    subgraph "Frappe Core" 
        HTTP["HTTP/TCP Server (Bench)"]:::core
        RPC["REST API / RPC Layer"]:::core
        Scheduler["Scheduler (Jobs)"]:::core
        ORM["ORM + MariaDB"]:::core
    end

    %% extended_calendars App
    subgraph "extended_calendars App"
        subgraph "Doctype Adapters"
            CHubMod["calendar_hubspot.py"]:::app
            CHubJSON["calendar_hubspot.json"]:::app
            CHubJS["calendar_hubspot.js"]:::app

            GHLMod["ghl_calendar.py"]:::app
            GHLJSON["ghl_calendar.json"]:::app
            GHLJS["ghl_calendar.js"]:::app

            GoujMod["goujana_calendar.py"]:::app
            GoujJSON["goujana_calendar.json"]:::app
            GoujJS["goujana_calendar.js"]:::app
        end

        subgraph "Hooks & Config"
            Hooks["hooks.py"]:::app
            Modules["modules.txt & config"]:::app
        end

        subgraph "Overrides"
            OContact["custom_contact.py"]:::app
            OEvent["custom_event.py"]:::app
            OGCal["custom_google_calendar.py"]:::app
        end

        subgraph "Patches & Migrations"
            Patch["v0_1 migrate_existing_calendars.py"]:::app
        end

        subgraph "Utilities & CI"
            Utils["utils.py"]:::app
            Packaging["pyproject.toml"]:::app
            CI[".github/workflows/ci.yml"]:::app
            CustJS["public/js/override/custom_event.js"]:::app
            JSONExt["custom/contact.json & event.json"]:::app
        end
    end

    %% Database
    DB["MariaDB / PostgreSQL"]:::db

    %% External APIs
    subgraph "External Calendar APIs"
        HubAPI["HubSpot Calendar API"]:::ext
        GHLAPI["GoHighLevel Calendar API"]:::ext
    end

    %% Connections
    User -->|"Interacts via JS"| HTTP
    HTTP --> RPC
    RPC --> CHubMod
    RPC --> GHLMod
    RPC --> GoujMod
    RPC --> OContact
    RPC --> OEvent
    RPC --> OGCal
    CHubMod --> DB
    GHLMod --> DB
    GoujMod --> DB
    OEvent --> DB
    OContact --> DB
    OGCal --> DB

    Scheduler -->|"Scheduled Sync"| Hooks
    Hooks --> CHubMod
    Hooks --> GHLMod
    Hooks --> GoujMod
    CHubMod -->|HTTP Sync| HubAPI
    GHLMod -->|HTTP Sync| GHLAPI
    HubAPI -->|HTTP Sync| CHubMod
    GHLAPI -->|HTTP Sync| GHLMod

    Patch --> DB
    Utils --> CHubMod
    Utils --> GHLMod
    Utils --> GoujMod

    %% Click Events
    click Hooks "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/hooks.py"
    click CHubMod "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/calendar_hubspot/calendar_hubspot.py"
    click CHubJSON "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/calendar_hubspot/calendar_hubspot.json"
    click CHubJS "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/calendar_hubspot/calendar_hubspot.js"
    click GHLMod "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/ghl_calendar/ghl_calendar.py"
    click GHLJSON "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/ghl_calendar/ghl_calendar.json"
    click GHLJS "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/ghl_calendar/ghl_calendar.js"
    click GoujMod "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/goujana_calendar/goujana_calendar.py"
    click GoujJSON "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/goujana_calendar/goujana_calendar.json"
    click GoujJS "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/doctype/goujana_calendar/goujana_calendar.js"
    click OContact "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/overrides/contact/custom_contact.py"
    click OEvent "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/overrides/event/custom_event.py"
    click OGCal "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/overrides/google_calendar/custom_google_calendar.py"
    click Patch "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/patches/v0_1/migrate_existing_calendars.py"
    click Modules "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/modules.txt"
    click Modules "https://github.com/0yeifer/any_calendar/tree/main/extended_calendars/config"
    click Utils "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/utils.py"
    click Packaging "https://github.com/0yeifer/any_calendar/blob/main/pyproject.toml"
    click CI "https://github.com/0yeifer/any_calendar/blob/main/.github/workflows/ci.yml"
    click CustJS "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/public/js/override/custom_event.js"
    click JSONExt "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/custom/contact.json"
    click JSONExt "https://github.com/0yeifer/any_calendar/blob/main/extended_calendars/extended_calendars/custom/event.json"

    %% Styles
    classDef users fill:#D5E8D4,stroke:#82B366;
    classDef core fill:#FFF2CC,stroke:#D6B656;
    classDef app fill:#E1D5E7,stroke:#9673A6;
    classDef db fill:#F8CECC,stroke:#B85450;
    classDef ext fill:#DAE8FC,stroke:#6C8EBF;
```
