# otiai10/copy architecture

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

- Interactive diagram: https://gitdiagram.com/otiai10/copy
- Repository: https://github.com/otiai10/copy

## Overview

##### Project type and purpose
- Project type: Go library/package for recursively copying directories/files with rich options.
- Purpose: Expose a high-level `Copy(src, dst, opts)` API that drives a pluggable, concurrent file‐copy engine preserving metadata, handling symlinks, errors, skips, etc.

##### File structure
- Top-level Go sources:
– copy.go: orchestration entrypoint (`Copy`, `CopyWithOptions`)
– options.go: definition of `Options` struct and default option values
– permission_control.go: strategy for setting file permissions
– preserve_*.go, stat_times_*.go: OS/platform‐specific metadata‐preservation logic
– copy_namedpipes.go, copy_namedpipes_x.go: named-pipe support
- Tests under root (`*_test.go`) and test data under `test/data/*`: drive various copy scenarios.
- CI workflows in `.github/workflows/`: go build/test, coverage, Docker/Vagrant, WASM, GopherJS.

##### Readme insights
- Public API surface: `Copy(src, dst)` plus `Options` for callbacks and flags.
- Key features: OnError, Skip, OnSymlink, OnDirExists, PermissionControl, PreserveTimes, PreserveOwner, concurrency control.

##### Main components & relationships
a. Public API Layer
– User code depends on this.

b. Core Copy Engine
– Component: “Engine/Orchestrator”
- Walks source tree (recursive or concurrent).
- For each entry, delegates to either “CopyFile”, “CopyDir”, or “HandleSymlink”.
- Applies buffering (CopyBufferSize), Sync, concurrency limiter.

c. Strategy Modules (injection points from Options)
– OnError handler
– Skip predicate
– OnSymlink action
– OnDirExists action
– RenameDestination hook
– PermissionControl hook
– PreferConcurrent decision

d. Filesystem Abstraction
– Default: OS filesystem via `os` and `io` packages.
– Optional: user-provided `fs.FS`.
– Named pipes: special handlers.

e. Metadata Preservation
– Submodules in preserve_*.go & stat_times_*.go
– Platform‐specific implementations (darwin, freebsd, js, windows, x)

f. Concurrency Control
– Uses `golang.org/x/sync/semaphore` when `NumOfWorkers > 1`
– PreferConcurrent determines per-directory parallelism

g. Testing Harness
– Unit tests (`*_test.go`)
– Integration tests under `test/data/...`
– Mock FS (embed) examples

h. CI/CD
– GitHub Actions workflows
– CodeQL, coverage, Docker/Vagrant/GopherJS/WASM builds

– Public API → Engine
– Engine → FS Abstraction (“ReadDir”, “OpenFile”, “CreateFile”)
– Engine → Metadata Preservation (calls to preserveTimes, preserveOwner, permission_control)
– Engine → Concurrency Controller (acquire/release semaphore)
– FS Abstraction → OS / Physical FS
– Optionally: Engine → Tests (for visualizing coverage of behavior)

##### Architectural patterns
– Strategy Pattern: Options struct injects behavior at runtime
– Decorator/Wrapper: Wrapping readers via `WrapReader`
– Adapter: fs.FS adapter for embedded filesystems
– Concurrency Limiting via semaphore

– Have you captured every major Go package/file concern?
– Are all injection points (Options) clearly shown?
– Have you annotated platform-specific modules?

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    UserApp["User Application"]:::external
    OSFS["OS / Physical Filesystem"]:::external
    CICD["CI/CD Services"]:::external

    %% Package Boundary
    subgraph "copy Package"
        direction TB
        PublicAPI["Public API"]:::public
        Engine["Engine / Orchestrator"]:::core
        Strategy["Strategy Modules (Options Hooks)"]:::strategy
        NamedPipe["Named-Pipe Support"]:::strategy
        FSAbst["Filesystem Abstraction"]:::core
        Metadata["Metadata Preservation Layer"]:::metadata
        PermissionControl["Permission Control"]:::strategy
        Concurrency["Concurrency Controller"]:::core
    end

    %% Relationships
    UserApp -->|"calls Copy(src, dst)"| PublicAPI
    PublicAPI -->|"orchestrates"| Engine
    Engine -->|“OnError, Skip, OnSymlink, OnDirExists, RenameDestination, PermissionControl, PreferConcurrent”| Strategy
    Engine -->|"handles named pipes"| NamedPipe
    Engine -->|"reads/writes"| FSAbst
    Engine -->|"preserves metadata"| Metadata
    Engine -->|"sets permissions"| PermissionControl
    Engine -->|"acquire/release semaphore"| Concurrency
    FSAbst -->|"system calls"| OSFS
    CICD -->|"runs workflows"| PublicAPI

    %% Click Events
    click PublicAPI "https://github.com/otiai10/copy/blob/main/copy.go"
    click PublicAPI "https://github.com/otiai10/copy/blob/main/options.go"
    click Engine "https://github.com/otiai10/copy/blob/main/copy.go"
    click Strategy "https://github.com/otiai10/copy/blob/main/options.go"
    click NamedPipe "https://github.com/otiai10/copy/blob/main/copy_namedpipes.go"
    click NamedPipe "https://github.com/otiai10/copy/blob/main/copy_namedpipes_x.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/preserve_ltimes.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/preserve_ltimes_x.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/preserve_owner.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/preserve_owner_x.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/preserve_times.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times_darwin.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times_freebsd.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times_js.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times_windows.go"
    click Metadata "https://github.com/otiai10/copy/blob/main/stat_times_x.go"
    click PermissionControl "https://github.com/otiai10/copy/blob/main/permission_control.go"

    %% Styles
    classDef public fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef core fill:#bbdefb,stroke:#1565c0,color:#1565c0
    classDef strategy fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef metadata fill:#d1c4e9,stroke:#6a1b9a,color:#4a148c
    classDef external fill:#eeeeee,stroke:#424242,color:#424242
```
