# akashrajpurohit/git-sync architecture

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

- Interactive diagram: https://gitdiagram.com/akashrajpurohit/git-sync
- Repository: https://github.com/akashrajpurohit/git-sync

## Overview

##### Project type and purpose
- This is a Go‑based CLI tool (“git‑sync”) whose sole purpose is to back up and periodically sync Git repositories from multiple hosting providers (GitHub, GitLab, Bitbucket, Gitea/Forgejo) into a local directory.

##### File structure
- cmd/ & main.go: CLI entrypoint & commands (root, version)
- pkg/config: configuration loader, defaults, validation
- pkg/token: token management for authentication
- pkg/client: generic HTTP client wrapper
- pkg/{github,gitlab,bitbucket,forgejo}: provider‑specific API adapters
- pkg/raw: raw Git operations (clone, fetch)
- pkg/sync: core sync engine (concurrency, retry, stats)
- pkg/notification: send post‑sync alerts (Gotify, ntfy)
- pkg/logger: structured logging
- systemd + Dockerfile: deployment options

##### Key README insights
- Supports CLI flags + YAML config for settings
- Concurrent sync, shallow/bare/mirror clones
- External notification hooks
- Multi‑platform provider support

##### Main components and interactions
a. Components
- CLI Layer (cmd/, entrypoint.sh)
- Configuration Manager (pkg/config)
- Authentication Manager (pkg/token)
- API Adapters (pkg/github, pkg/gitlab, pkg/bitbucket, pkg/forgejo)
- Core Sync Engine (pkg/sync)
- Git Executor (pkg/raw)
- Notification Service (pkg/notification)
- Logging Service (pkg/logger)
- File System (local backup directory)
- External Services (Git providers, Gotify/ntfy endpoints)

b. Relationships & Data Flow
1. User invokes CLI → CLI Layer
2. CLI reads/parses CLI flags & loads YAML via Configuration Manager
3. Configuration Manager validates settings
4. Authentication Manager retrieves or refreshes tokens for each provider
5. For each provider: API Adapter calls provider’s REST API to list repositories
6. Core Sync Engine schedules jobs (concurrency manager, retry logic)
7. For each repository job: Git Executor (bare/shallow/mirror) reads/writes to File System
8. Sync Engine updates stats
9. Upon completion or error: Notification Service posts to configured channels
10. Logging Service records structured logs throughout

c. Architectural patterns & principles
- Modular provider abstraction (one pkg per host)
- Dependency injection via interfaces (client, logger, notification)
- Worker pool / concurrency pattern for parallel sync
- Retry decorator in sync module
- Single responsibility per package

d. Key technologies/frameworks
- Go modules (go.mod)
- Cobra (CLI parsing in cmd/)
- net/http via pkg/client
- Git CLI invoked in pkg/raw
- systemd unit & Dockerfile for deployment
- YAML config

##### Essential details to capture
- All major pkg/ subdirectories as modules
- Config & token retrieval before any sync
- Parallel sync jobs with retry & stats tracking
- Raw Git operations writing to the file system
- Notification & logging as first‑class citizens
- Deployment options (systemd, container)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        RootCmd["Root Command"]:::coreblue
        VersionCmd["Version Command"]:::coreblue
        Main["main.go"]:::coreblue
        Entrypoint["entrypoint.sh"]:::coreblue
    end

    %% Core Logic
    subgraph "Core Logic"
        ConfigLoader["Config Loader"]:::coreblue
        Defaults["Config Defaults"]:::coreblue
        Validation["Config Validation"]:::coreblue
        TokenManager["Token Manager"]:::coreblue
        HTTPClient["HTTP Client"]:::coreblue
        subgraph "Sync Engine"
            SyncCore["Sync Core"]:::coreblue
            Concurrency["Concurrency Manager"]:::coreblue
            Retry["Retry Logic"]:::coreblue
            Stats["Stats Tracker"]:::coreblue
        end
        GitExecutor["Git Executor"]:::coreblue
        FS[(Local Backup Dir)]:::coreblue
        VersionInfo["Version Info"]:::coreblue
    end

    %% API Adapters
    subgraph "API Adapters"
        GitHubAdapter["GitHub Adapter"]:::extgreen
        GitLabAdapter["GitLab Adapter"]:::extgreen
        BitbucketAdapter["Bitbucket Adapter"]:::extgreen
        ForgejoAdapter["Forgejo Adapter"]:::extgreen
    end

    %% Services
    subgraph "Services"
        NotificationCore["Notification Service"]:::svcorange
        GotifyEP["Gotify Endpoint"]:::extgreen
        ntfyEP["ntfy Endpoint"]:::extgreen
        Logging["Logging Service"]:::svcorange
    end

    %% Deployment
    subgraph "Deployment"
        Docker["Dockerfile"]:::depgray
        Systemd["systemd/gitsync.service"]:::depgray
    end

    %% External Services
    subgraph "External Services"
        GitHubAPI["GitHub API"]:::extgreen
        GitLabAPI["GitLab API"]:::extgreen
        BitbucketAPI["Bitbucket API"]:::extgreen
        ForgejoAPI["Forgejo API"]:::extgreen
    end

    %% Connections
    RootCmd -->|invokes| ConfigLoader
    VersionCmd -->|invokes| VersionInfo
    Main --> RootCmd
    Main --> VersionCmd
    Entrypoint --> Main

    ConfigLoader --> Defaults
    Defaults --> Validation
    Validation --> TokenManager
    TokenManager --> HTTPClient

    HTTPClient --> GitHubAdapter
    HTTPClient --> GitLabAdapter
    HTTPClient --> BitbucketAdapter
    HTTPClient --> ForgejoAdapter

    GitHubAdapter -->|REST calls| GitHubAPI
    GitLabAdapter -->|REST calls| GitLabAPI
    BitbucketAdapter -->|REST calls| BitbucketAPI
    ForgejoAdapter -->|REST calls| ForgejoAPI

    GitHubAdapter --> SyncCore
    GitLabAdapter --> SyncCore
    BitbucketAdapter --> SyncCore
    ForgejoAdapter --> SyncCore

    SyncCore --> Concurrency
    Concurrency --> Retry
    Retry --> Stats
    Stats --> GitExecutor

    GitExecutor --> FS

    SyncCore --> NotificationCore
    NotificationCore --> GotifyEP
    NotificationCore --> ntfyEP

    %% Logging taps into multiple stages
    ConfigLoader --> Logging
    TokenManager --> Logging
    GitHubAdapter --> Logging
    SyncCore --> Logging
    NotificationCore --> Logging
    Logging --> FS

    %% Deployment options
    Entrypoint --> Docker
    Entrypoint --> Systemd

    %% Click Events
    click RootCmd "https://github.com/akashrajpurohit/git-sync/blob/main/cmd/root.go"
    click VersionCmd "https://github.com/akashrajpurohit/git-sync/blob/main/cmd/version.go"
    click Main "https://github.com/akashrajpurohit/git-sync/blob/main/main.go"
    click Entrypoint "https://github.com/akashrajpurohit/git-sync/blob/main/entrypoint.sh"
    click ConfigLoader "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/config/config.go"
    click Defaults "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/config/defaults.go"
    click Validation "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/config/validate.go"
    click TokenManager "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/token/manager.go"
    click HTTPClient "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/client/client.go"
    click GitHubAdapter "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/github/github.go"
    click GitLabAdapter "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/gitlab/gitlab.go"
    click BitbucketAdapter "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/bitbucket/bitbucket.go"
    click ForgejoAdapter "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/forgejo/forgejo.go"
    click SyncCore "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/sync/sync.go"
    click Concurrency "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/sync/concurrency.go"
    click Retry "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/sync/retry.go"
    click Stats "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/sync/stats.go"
    click GitExecutor "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/raw/raw.go"
    click NotificationCore "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/notification/notification.go"
    click GotifyEP "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/notification/gotify.go"
    click ntfyEP "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/notification/ntfy.go"
    click Logging "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/logger/logger.go"
    click VersionInfo "https://github.com/akashrajpurohit/git-sync/blob/main/pkg/version/version.go"
    click Docker "https://github.com/akashrajpurohit/git-sync/tree/main/Dockerfile"
    click Systemd "https://github.com/akashrajpurohit/git-sync/blob/main/systemd/gitsync.service"

    %% Styles
    classDef coreblue fill:#D0E8FF,stroke:#0066CC,color:#003366
    classDef extgreen fill:#E0F8E0,stroke:#28A745,color:#155724
    classDef svcorange fill:#FFF4E5,stroke:#FFA500,color:#663C00
    classDef depgray fill:#F0F0F0,stroke:#AAAAAA,color:#555555
```
