# johannesboyne/gofakes3 architecture

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

- Interactive diagram: https://gitdiagram.com/johannesboyne/gofakes3
- Repository: https://github.com/johannesboyne/gofakes3

## Overview

GoFakeS3 is a local S3-compatible fake server and integration-testing library. The principal workflow is an S3 client sending HTTP requests to the server, which routes S3 operations to a selected storage backend and returns S3-style responses. The repository also provides multipart-upload handling, versioned in-memory storage, and filesystem- and Bolt-backed storage options. The README documents the server setup and backend selection; routing and storage relationships are shown only where the excerpts support them, so some backend-dispatch links remain unverified.

Main entry points: [`backend.go`](https://github.com/johannesboyne/gofakes3/blob/master/backend.go) (Backend Contract), [`internal/s3io/io.go`](https://github.com/johannesboyne/gofakes3/blob/master/internal/s3io/io.go) (I/O Helpers), [`gofakes3.go`](https://github.com/johannesboyne/gofakes3/blob/master/gofakes3.go) (HTTP Server API), [`backend/s3mem/backend.go`](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3mem/backend.go) (Memory Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["S3 Server"]
  node_cli["Server CLI<br/>[main.go]"]
  node_server_api["HTTP Server API<br/>[gofakes3.go]"]
  node_routing["Request Router<br/>[routing.go]"]
end

subgraph group_operations["S3 Operations"]
  node_ops["S3 Operations<br/>[gofakes3.go]"]
  node_multipart["Multipart Uploads<br/>[uploader.go]"]
end

subgraph group_storage["Storage Backends"]
  node_backend_contract["Backend Contract<br/>[backend.go]"]
  node_mem_backend[("Memory Backend<br/>[backend.go]")]
  node_mem_bucket[("Bucket Versions<br/>[bucket.go]")]
  node_bolt_backend[("Bolt Backend<br/>[backend.go]")]
  node_bolt_schema["Bolt Schema<br/>[schema.go]"]
  node_multi_fs[("Multi-Bucket FS<br/>[multi.go]")]
  node_single_fs[("Single-Bucket FS<br/>[single.go]")]
end

subgraph group_internals["Storage Internals"]
  node_s3io["I/O Helpers<br/>[io.go]"]
end

node_client(("S3 Client"))

node_client -->|"sends S3 requests"| node_server_api
node_server_api -.->|"routes requests"| node_routing
node_routing -->|"dispatches operations"| node_ops
node_ops -.->|"uses backend"| node_backend_contract
node_cli -.->|"serves handler"| node_server_api
node_mem_backend -.->|"implements"| node_backend_contract
node_bolt_backend -.->|"implements"| node_backend_contract
node_multi_fs -.->|"implements"| node_backend_contract
node_single_fs -.->|"implements"| node_backend_contract
node_mem_backend -->|"uses bucket state"| node_mem_bucket
node_bolt_backend -->|"stores schema data"| node_bolt_schema
node_multipart -->|"uses storage"| node_backend_contract
node_multi_fs -->|"uses I/O helper"| node_s3io
node_single_fs -->|"uses I/O helper"| node_s3io
node_mem_bucket -->|"uses I/O helper"| node_s3io
node_bolt_schema -->|"uses I/O helper"| node_s3io

click node_cli "https://github.com/johannesboyne/gofakes3/blob/master/cmd/gofakes3/main.go"
click node_server_api "https://github.com/johannesboyne/gofakes3/blob/master/gofakes3.go"
click node_routing "https://github.com/johannesboyne/gofakes3/blob/master/routing.go"
click node_ops "https://github.com/johannesboyne/gofakes3/blob/master/gofakes3.go"
click node_multipart "https://github.com/johannesboyne/gofakes3/blob/master/uploader.go"
click node_backend_contract "https://github.com/johannesboyne/gofakes3/blob/master/backend.go"
click node_mem_backend "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3mem/backend.go"
click node_mem_bucket "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3mem/bucket.go"
click node_bolt_backend "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3bolt/backend.go"
click node_bolt_schema "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3bolt/schema.go"
click node_multi_fs "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3afero/multi.go"
click node_single_fs "https://github.com/johannesboyne/gofakes3/blob/master/backend/s3afero/single.go"
click node_s3io "https://github.com/johannesboyne/gofakes3/blob/master/internal/s3io/io.go"

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_cli,node_server_api,node_routing,node_client toneBlue
class node_ops,node_multipart toneAmber
class node_backend_contract,node_mem_backend,node_mem_bucket,node_bolt_backend,node_bolt_schema,node_multi_fs,node_single_fs toneMint
class node_s3io toneRose
```

## Components

### S3 Server

- [Server CLI](https://github.com/johannesboyne/gofakes3/blob/master/cmd/gofakes3/main.go): `cmd/gofakes3/main.go`
- [HTTP Server API](https://github.com/johannesboyne/gofakes3/blob/master/gofakes3.go): `gofakes3.go`
- [Request Router](https://github.com/johannesboyne/gofakes3/blob/master/routing.go): `routing.go`

### S3 Operations

- [S3 Operations](https://github.com/johannesboyne/gofakes3/blob/master/gofakes3.go): `gofakes3.go`
- [Multipart Uploads](https://github.com/johannesboyne/gofakes3/blob/master/uploader.go): `uploader.go`

### Storage Backends

- [Backend Contract](https://github.com/johannesboyne/gofakes3/blob/master/backend.go): `backend.go`
- [Memory Backend](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3mem/backend.go): `backend/s3mem/backend.go`
- [Bucket Versions](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3mem/bucket.go): `backend/s3mem/bucket.go`
- [Bolt Backend](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3bolt/backend.go): `backend/s3bolt/backend.go`
- [Bolt Schema](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3bolt/schema.go): `backend/s3bolt/schema.go`
- [Multi-Bucket FS](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3afero/multi.go): `backend/s3afero/multi.go`
- [Single-Bucket FS](https://github.com/johannesboyne/gofakes3/blob/master/backend/s3afero/single.go): `backend/s3afero/single.go`

### Storage Internals

- [I/O Helpers](https://github.com/johannesboyne/gofakes3/blob/master/internal/s3io/io.go): `internal/s3io/io.go`

### Other components

- **S3 Client**

## Connections

- S3 Client → HTTP Server API: sends S3 requests
- HTTP Server API → Request Router: routes requests
- Request Router → S3 Operations: dispatches operations (evidence: `routing.go`)
- S3 Operations → Backend Contract: uses backend
- Server CLI → HTTP Server API: serves handler
- Memory Backend → Backend Contract: implements
- Bolt Backend → Backend Contract: implements
- Multi-Bucket FS → Backend Contract: implements
- Single-Bucket FS → Backend Contract: implements
- Memory Backend → Bucket Versions: uses bucket state (evidence: `backend/s3mem/backend.go`)
- Bolt Backend → Bolt Schema: stores schema data (evidence: `backend/s3bolt/backend.go`)
- Multipart Uploads → Backend Contract: uses storage (evidence: `uploader.go`)
- Multi-Bucket FS → I/O Helpers: uses I/O helper (evidence: `backend/s3afero/multi.go`)
- Single-Bucket FS → I/O Helpers: uses I/O helper (evidence: `backend/s3afero/single.go`)
- Bucket Versions → I/O Helpers: uses I/O helper (evidence: `backend/s3mem/bucket.go`)
- Bolt Schema → I/O Helpers: uses I/O helper (evidence: `backend/s3bolt/schema.go`)
