# scribd/objinsync architecture

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

- Interactive diagram: https://gitdiagram.com/scribd/objinsync
- Repository: https://github.com/scribd/objinsync

## Overview

##### Project type and purpose
- ObjInSync is a Go-based command-line tool plus daemon that continuously and incrementally synchronizes a directory from a remote object store (e.g., AWS S3 or Minio) to a local file system.
- It exposes health and Prometheus metrics endpoints when running in long-running (“daemon”) mode and integrates with Sentry for error reporting.

##### File structure
- Top‐level:
- main.go: CLI entrypoint using Cobra/Viper-style command parsing (pull command, flags, daemon vs once).
- go.mod / go.sum: Go module definitions.
- Dockerfile, .dockerignore, Makefile, .github/workflows/cicd.yml, goreleaser.yml: build, CI/CD, containerization, and release automation.
- pkg/sync: core sync logic—dir.go and pull.go contain the pull algorithms; internal tests verify correctness.

##### README insights
- Commands: `objinsync pull` with flags for interval, once, exclude patterns, custom endpoints, SSL, status/metrics ports.
- Behavior: single-run (“once”) vs continuous polling (default 5s interval).
- Monitoring: HTTP server on default port 8087 serving /health and /metrics.
- Integrations: AWS SDK (S3), Prometheus client, Sentry SDK.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Daemon Layer
    subgraph "CLI / Daemon Layer"
        direction TB
        Config["Config (flags, env vars)"]:::core
        CLI["CLI/Daemon Entrypoint\n(main.go)"]:::core
        HTTPServer["HTTP Server (/health, /metrics)"]:::core
    end

    %% Sync Engine
    subgraph "Synchronization Engine\n(pkg/sync)" 
        direction TB
        Walker["Directory Walker\n(pkg/sync/dir.go)"]:::core
        Scheduler["Pull Scheduler & Downloader\n(pkg/sync/pull.go)"]:::core
        MetricsCollector["Metrics Collector"]:::core
    end

    %% External Services
    subgraph "External Services"
        direction TB
        S3["AWS S3 / Minio"]:::external
        Prometheus["Prometheus Scraper"]:::external
        Sentry["Sentry Service"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        LocalFS["Local File System"]:::infra
    end

    %% CI/CD & Release Pipeline
    subgraph "CI/CD & Release Pipeline"
        direction TB
        GitHubCI["GitHub Actions CI\n(.github/workflows/cicd.yml)"]:::infra
        DockerBuild["Dockerfile & .dockerignore"]:::infra
        GoReleaser["GoReleaser Config\n(goreleaser.yml)"]:::infra
        Make["Makefile"]:::infra
        GoMod["go.mod / go.sum"]:::infra
        README["README.md"]:::infra
    end

    %% Connections
    Config --> CLI
    CLI --> Scheduler
    CLI --> HTTPServer
    Scheduler --> Walker
    Scheduler --> S3
    Walker --> LocalFS
    Scheduler --> MetricsCollector
    MetricsCollector --> HTTPServer
    HTTPServer --> Prometheus
    Scheduler -->|Error events| Sentry

    %% Tests
    subgraph "Core Sync Tests"
        direction TB
        DirTest["dir_internal_test.go"]:::infra
        PullTest["pull_internal_test.go"]:::infra
    end
    Walker --> DirTest
    Scheduler --> PullTest

    %% Build Pipeline Flow
    GitHubCI --> DockerBuild
    GitHubCI --> GoReleaser
    GitHubCI --> Make
    GoReleaser --> DockerBuild

    %% Click Events
    click CLI "https://github.com/scribd/objinsync/blob/master/main.go"
    click HTTPServer "https://github.com/scribd/objinsync/blob/master/main.go"
    click Walker "https://github.com/scribd/objinsync/blob/master/pkg/sync/dir.go"
    click Scheduler "https://github.com/scribd/objinsync/blob/master/pkg/sync/pull.go"
    click DirTest "https://github.com/scribd/objinsync/blob/master/pkg/sync/dir_internal_test.go"
    click PullTest "https://github.com/scribd/objinsync/blob/master/pkg/sync/pull_internal_test.go"
    click GitHubCI "https://github.com/scribd/objinsync/blob/master/.github/workflows/cicd.yml"
    click GoReleaser "https://github.com/scribd/objinsync/blob/master/.goreleaser.yml"
    click DockerBuild "https://github.com/scribd/objinsync/tree/master/Dockerfile"
    click DockerBuild "https://github.com/scribd/objinsync/blob/master/.dockerignore"
    click Make "https://github.com/scribd/objinsync/tree/master/Makefile"
    click GoMod "https://github.com/scribd/objinsync/blob/master/go.mod"
    click GoMod "https://github.com/scribd/objinsync/blob/master/go.sum"
    click README "https://github.com/scribd/objinsync/blob/master/README.md"

    %% Styles
    classDef core fill:#e0ffe0,stroke:#2e8b57,color:#084c23
    classDef external fill:#e0f0ff,stroke:#1f4e79,color:#062544
    classDef infra fill:#f0f0f0,stroke:#888888,color:#333333
```
