# wurthel/git-remote-s3 architecture

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

- Interactive diagram: https://gitdiagram.com/wurthel/git-remote-s3
- Repository: https://github.com/wurthel/git-remote-s3

## Overview

git-remote-s3 presents S3 as a Git remote and Git LFS storage service. Git invokes the remote helper for fetch/push operations; the helper stores Git bundles (and, for s3+zip remotes, ZIP archives) in S3. Git LFS separately invokes the custom transfer process to upload or download objects. The management CLI inspects and administers refs, branch protection, and stale locks. The excerpts establish these entry points and helper relationships, but do not expose every internal dispatch or storage operation, so those links are omitted where not evidenced.

Main entry points: [`git_remote_s3/remote.py`](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/remote.py) (Remote helper), [`git_remote_s3/lfs.py`](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/lfs.py) (Custom transfer), [`git_remote_s3/common.py`](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/common.py) (S3 URI parser), [`git_remote_s3/manage.py`](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/manage.py) (Repository doctor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_remote["Git remote"]
  node_remote_helper["Remote helper<br/>[remote.py]"]
  node_git_ops["Bundle and archive<br/>[git.py]"]
end

subgraph group_lfs["LFS transfer"]
  node_lfs_transfer["Custom transfer<br/>[lfs.py]"]
end

subgraph group_admin["Remote management"]
  node_doctor["Repository doctor<br/>[manage.py]"]
  node_branch_admin["Branch administration<br/>[manage.py]"]
end

subgraph group_shared["Shared internals"]
  node_url_parser["S3 URI parser<br/>[common.py]"]
  node_uri_scheme["URI schemes<br/>[enums.py]"]
end

node_git(("Git client"))
node_s3[("Amazon S3")]
node_lfs_client(("Git LFS"))

node_git -->|"invokes helper"| node_remote_helper
node_remote_helper -->|"parses URI"| node_url_parser
node_url_parser -->|"uses scheme"| node_uri_scheme
node_remote_helper -->|"reads and writes"| node_s3
node_remote_helper -->|"creates bundles"| node_git_ops
node_git -->|"requests transfer"| node_lfs_client
node_lfs_client -->|"invokes custom transfer"| node_lfs_transfer
node_lfs_transfer -->|"parses URI"| node_url_parser
node_lfs_transfer -->|"validates ref"| node_git_ops
node_lfs_transfer -->|"uploads and downloads"| node_s3
node_doctor -->|"parses remote"| node_url_parser
node_doctor -->|"inspects and repairs"| node_s3
node_branch_admin -->|"manages branches"| node_s3

click node_remote_helper "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/remote.py"
click node_git_ops "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/git.py"
click node_lfs_transfer "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/lfs.py"
click node_doctor "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/manage.py"
click node_branch_admin "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/manage.py"
click node_url_parser "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/common.py"
click node_uri_scheme "https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/enums.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_remote_helper,node_git_ops,node_git toneBlue
class node_lfs_transfer,node_s3 toneAmber
class node_doctor,node_branch_admin toneMint
class node_url_parser,node_uri_scheme toneRose
class node_lfs_client toneIndigo
```

## Components

### Git remote

- [Remote helper](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/remote.py): `git_remote_s3/remote.py`
- [Bundle and archive](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/git.py): `git_remote_s3/git.py`

### LFS transfer

- [Custom transfer](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/lfs.py): `git_remote_s3/lfs.py`

### Remote management

- [Repository doctor](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/manage.py): `git_remote_s3/manage.py`
- [Branch administration](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/manage.py): `git_remote_s3/manage.py`

### Shared internals

- [S3 URI parser](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/common.py): `git_remote_s3/common.py`
- [URI schemes](https://github.com/wurthel/git-remote-s3/blob/fork-main/git_remote_s3/enums.py): `git_remote_s3/enums.py`

### Other components

- **Git client**
- **Amazon S3**
- **Git LFS**

## Connections

- Git client → Remote helper: invokes helper (evidence: `README.md`)
- Remote helper → S3 URI parser: parses URI (evidence: `git_remote_s3/remote.py`)
- S3 URI parser → URI schemes: uses scheme (evidence: `git_remote_s3/common.py`)
- Remote helper → Amazon S3: reads and writes (evidence: `git_remote_s3/remote.py`)
- Remote helper → Bundle and archive: creates bundles (evidence: `README.md`)
- Git client → Git LFS: requests transfer (evidence: `README.md`)
- Git LFS → Custom transfer: invokes custom transfer (evidence: `README.md`)
- Custom transfer → S3 URI parser: parses URI (evidence: `git_remote_s3/lfs.py`)
- Custom transfer → Bundle and archive: validates ref (evidence: `git_remote_s3/lfs.py`)
- Custom transfer → Amazon S3: uploads and downloads (evidence: `git_remote_s3/lfs.py`)
- Repository doctor → S3 URI parser: parses remote (evidence: `git_remote_s3/manage.py`)
- Repository doctor → Amazon S3: inspects and repairs (evidence: `git_remote_s3/manage.py`)
- Branch administration → Amazon S3: manages branches (evidence: `git_remote_s3/manage.py`)
