# randilt/geckos3 architecture

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

- Interactive diagram: https://gitdiagram.com/randilt/geckos3
- Repository: https://github.com/randilt/geckos3

## Overview

**GeckoS3** is a **single-binary Go HTTP server** that implements a **subset of the S3 API** and persists data to the **local filesystem**:
- **Buckets ⇢ directories** under a configurable data directory (`-data-dir` / `GECKOS3_DATA_DIR`)
- **Objects ⇢ files** inside bucket directories (nested keys create subdirectories)
- **Object metadata ⇢ `.metadata.json` sidecar files**
- Optional **AWS Signature V4** auth (`-auth` / `GECKOS3_AUTH_ENABLED`)
- Designed for **local dev/CI/single-node** usage (explicitly not HA/clustered)

- an **S3-compatible HTTP façade**
- with **auth middleware**
- a **request handler/router** implementing S3 operations
- a **storage layer** mapping S3 semantics onto filesystem + metadata
- plus **logging** and **health check** concerns
- optionally containerized via Docker with a mounted volume

- `main.go`
**Composition root**: parses flags/env, constructs dependencies (auth/storage/logger), starts HTTP server on `-listen` / `GECKOS3_LISTEN`.

- `handler.go`
**HTTP routing + S3 API implementation**: endpoints listed in README (ListBuckets, PutObject, GetObject, ListObjectsV1/V2, etc.). Likely dispatches based on method/path/query.

- `auth.go`
**SigV4 authentication/authorization middleware**:
- validates header-signed requests
- validates presigned URLs
- bypass for `GET /health` (explicit requirement)

- `storage.go`
**Persistence adapter**: filesystem operations:
- create/delete bucket directories
- atomic writes (temp + fsync + rename)
- range reads
- copy semantics (via `x-amz-copy-source`)
- path traversal protection (keys escaping data dir rejected)
- metadata read/write to `.metadata.json`

- `logging.go`
**Request logging**: structured JSON logs to stdout (request_id, duration_ms, bytes, etc.)

- Tests:
- `*_test.go`, `integration_test.go`

- Deployment/build:
- `Dockerfile`, `docker-compose.yml`, `Dockerfile.goreleaser`, `.goreleaser.yaml`, `Makefile`
These become “deployment view” artifacts: container, port mapping, volume mount, healthcheck.

This repo strongly suggests a **layered single-service** design:

##### Cross-cutting middleware: auth + logging + health bypass
3. **Application/endpoint layer**: S3 operation handlers (request parsing, XML responses, headers)
##### Infrastructure: local disk / mounted volume

- **Auth boundary**: SigV4 verification is the “trust gate” for all S3 endpoints except `/health`
- **Atomic write guarantee**: temp file → fsync → rename (annotate on PutObject path)
- **Path traversal protection**: reject keys escaping data dir (annotate in Storage)
- **Range reads**: GetObject supports `Range` (annotate response path)

Given the README, accuracy hinges on capturing these specifics:

**Endpoints**
- S3 root: `GET /` (ListBuckets)
- Bucket ops: `PUT/DELETE/HEAD /{bucket}`, `GET /{bucket}` (ListObjects v1/v2)
- Object ops: `PUT/GET/HEAD/DELETE /{bucket}/{key}`
- `POST /{bucket}?delete` (DeleteObjects)
- Copy via `PUT ...` + `x-amz-copy-source`
- Health: `GET /health` (no auth)

**Storage mapping**
- “Bucket directory” and “Object file”
- “Sidecar metadata `.metadata.json`”
- “Nested keys create directories”
- “Atomic write” + “fsync”
- “Path traversal blocked”

**Auth**
- “AWS SigV4 (header + presigned URL)”
- “Can be disabled”

**Logging**
- “JSON logs to stdout”

- External actors (clients) = gray
- Runtime components (Go service internals) = blue
- **Trust boundary line**:
- An explicit boundary around “Authenticated S3 API”
- `/health` bypassing it
- **Annotate key constraints** directly on components (small callouts):
- “No multipart”, “single-node”, “no TLS built-in”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% A) System Context Diagram
    %% =========================
    subgraph "A) System Context (Who uses GeckoS3)"
        direction TB

        Dev["Developers / CI Pipelines"]:::external
        Clients["S3 Clients\n(AWS CLI / boto3 / SDKs)"]:::external

        Proxy["Optional Reverse Proxy\n(TLS / rate limiting)\n(Not in repo)"]:::optional

        subgraph "GeckoS3 Service (S3-compatible HTTP façade)"
            direction TB
            GeckoS3["GeckoS3\nSingle-binary Go HTTP server\n(S3 subset; single-node; no TLS built-in)"]:::service
        end

        Disk[("Local Filesystem / Host Volume\nData Directory")]:::datastore
        Meta[("Sidecar Metadata Files\n*.metadata.json")]:::datastore

        Dev -->|"uses"| Clients
        Clients -->|"S3_API_calls"| Proxy
        Clients -->|"S3_API_calls"| GeckoS3
        Proxy -->|"forwards_HTTP"| GeckoS3

        GeckoS3 -->|"reads/writes"| Disk
        Disk -->|"stores"| Meta
    end

    %% =========================
    %% B) Container / Deployment
    %% =========================
    subgraph "B) Deployment (Native binary or Docker/Compose)"
        direction TB

        subgraph "Option 1: Native Host Process"
            direction TB
            HostCfg["Flags/Env\n(-listen,-data-dir,-auth,\nGECKOS3_*)"]:::config
            HostProc["GeckoS3 Host Process\n(listen :9000 default)"]:::service
            HostDisk[("Host Disk\nData Dir")]:::datastore
            HostCfg -.->|"configures"| HostProc
            HostProc -->|"reads/writes"| HostDisk
        end

        subgraph "Option 2: Docker / Compose"
            direction TB
            Compose["docker-compose.yml\nports: 9000:9000\nvolume: ./data:/data\nenv: creds/auth/data-dir\nhealthcheck: GET /health"]:::deploy
            Image["Docker Image\n(Dockerfile)"]:::deploy
            Container["Container: geckos3\nExposes :9000\nMounts /data"]:::service
            Vol[("Mounted Volume\n/data")]:::datastore
            Health["Healthcheck Client\n(GET /health)"]:::external

            Compose -->|"build/run"| Image
            Image -->|"runs"| Container
            Compose -->|"orchestrates"| Container
            Container -->|"reads/writes"| Vol
            Health -->|"GET_/health"| Container
        end
    end

    %% =========================
    %% C) Component Diagram (Inside Service)
    %% =========================
    subgraph "C) GeckoS3 Internal Components (Single Process)"
        direction TB

        Main["Bootstrap / Composition Root\n(main.go)\nParse flags+env; wire deps; start net/http server"]:::component

        subgraph "HTTP Transport + Middleware Chain"
            direction TB

            HTTP["HTTP Server / Listener\n(net/http)\n(listen addr from config)"]:::component

            HealthBypass["Health Handler\nGET /health\n(No auth)"]:::component

            Logger["Request Logging Middleware\n(logging.go)\nJSON logs to stdout\n(request_id,duration_ms,bytes,...)"]:::middleware

            Auth["SigV4 Auth Middleware\n(auth.go)\nHeader-signed + presigned URLs\n(Enabled/disabled by config)"]:::middleware

            Router["Router / S3 API Handlers\n(handler.go)\nListBuckets; Bucket ops;\nObject ops; DeleteObjects;\nCopy via x-amz-copy-source"]:::component
        end

        Storage["Storage Adapter\n(storage.go)\nBuckets->dirs; Objects->files\nNested keys -> subdirs\nPath traversal blocked\nAtomic writes: temp+fsync+rename\nRange reads support\nMetadata sidecars"]:::storage

        FS[("Local Filesystem\n(data dir)")]:::datastore
        Sidecar[("Metadata Sidecars\n*.metadata.json")]:::datastore

        Stdout["stdout (JSON logs)"]:::external

        %% Wiring / order
        Main -->|"starts"| HTTP

        %% Request path
        HTTP -->|"route_/health"| HealthBypass
        HTTP -->|"all_other_requests"| Logger
        Logger -->|"next"| Auth
        Auth -->|"authorized_request"| Router

        %% Storage
        Router -->|"S3_ops_call"| Storage
        Storage -->|"read/write_files"| FS
        Storage -->|"read/write"| Sidecar

        %% Cross-cutting outputs
        Logger -.->|"writes_logs"| Stdout

        %% Trust boundary (conceptual)
        TrustNote["Trust boundary:\nAuthenticated S3 API\n(All endpoints except /health)"]:::note
        Auth -.->|"enforces"| TrustNote
        HealthBypass -.->|"bypasses_auth"| TrustNote
    end

    %% =========================
    %% Bonus: Representative PutObject Sequence (compact)
    %% =========================
    subgraph "Representative Flow: PutObject (Atomic write + metadata)"
        direction TB
        C1["Client PUT /{bucket}/{key}"]:::external
        C2["Logging"]:::middleware
        C3["SigV4 Verify\n(or disabled)"]:::middleware
        C4["PutObject Handler"]:::component
        C5["Storage: temp->fsync->rename\nWrite *.metadata.json"]:::storage
        C6[("Disk (/data)")]:::datastore

        C1 -->|"HTTP_request"| C2 -->|"next"| C3 -->|"ok"| C4 -->|"call"| C5 -->|"persist"| C6
    end

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click Main "https://github.com/randilt/geckos3/blob/master/main.go"
    click Router "https://github.com/randilt/geckos3/blob/master/handler.go"
    click HealthBypass "https://github.com/randilt/geckos3/blob/master/handler.go"
    click Auth "https://github.com/randilt/geckos3/blob/master/auth.go"
    click Storage "https://github.com/randilt/geckos3/blob/master/storage.go"
    click Logger "https://github.com/randilt/geckos3/blob/master/logging.go"

    click Compose "https://github.com/randilt/geckos3/blob/master/docker-compose.yml"
    click Image "https://github.com/randilt/geckos3/tree/master/Dockerfile"

    click HostProc "https://github.com/randilt/geckos3/blob/master/main.go"
    click TrustNote "https://github.com/randilt/geckos3/blob/master/README.md"

    click C4 "https://github.com/randilt/geckos3/blob/master/handler.go"
    click C5 "https://github.com/randilt/geckos3/blob/master/storage.go"

    %% Test & tooling artifacts (clickable, not runtime)
    TestAuth["auth_test.go"]:::artifact
    TestHandler["handler_test.go"]:::artifact
    TestStorage["storage_test.go"]:::artifact
    TestIntegration["integration_test.go"]:::artifact
    GoreleaserDf["Dockerfile.goreleaser"]:::artifact
    GoreleaserCfg[".goreleaser.yaml"]:::artifact
    Make["Makefile"]:::artifact
    Readme["README.md"]:::artifact
    AwsCli["test-aws-cli.sh"]:::artifact
    Boto3["test-boto3.py"]:::artifact

    click TestAuth "https://github.com/randilt/geckos3/blob/master/auth_test.go"
    click TestHandler "https://github.com/randilt/geckos3/blob/master/handler_test.go"
    click TestStorage "https://github.com/randilt/geckos3/blob/master/storage_test.go"
    click TestIntegration "https://github.com/randilt/geckos3/blob/master/integration_test.go"
    click GoreleaserDf "https://github.com/randilt/geckos3/blob/master/Dockerfile.goreleaser"
    click GoreleaserCfg "https://github.com/randilt/geckos3/blob/master/.goreleaser.yaml"
    click Make "https://github.com/randilt/geckos3/tree/master/Makefile"
    click Readme "https://github.com/randilt/geckos3/blob/master/README.md"
    click AwsCli "https://github.com/randilt/geckos3/blob/master/test-aws-cli.sh"
    click Boto3 "https://github.com/randilt/geckos3/blob/master/test-boto3.py"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px;
    classDef service fill:#DBEAFE,stroke:#1D4ED8,color:#0B1220,stroke-width:1.5px;
    classDef component fill:#BFDBFE,stroke:#1D4ED8,color:#0B1220,stroke-width:1px;
    classDef middleware fill:#C7D2FE,stroke:#4338CA,color:#0B1220,stroke-width:1px;
    classDef storage fill:#A7F3D0,stroke:#047857,color:#06281A,stroke-width:1px;
    classDef datastore fill:#BBF7D0,stroke:#166534,color:#052E16,stroke-width:1.5px;
    classDef deploy fill:#FED7AA,stroke:#C2410C,color:#1F1307,stroke-width:1px;
    classDef config fill:#FEF3C7,stroke:#B45309,color:#1F1307,stroke-width:1px;
    classDef optional fill:#F3F4F6,stroke:#9CA3AF,color:#111827,stroke-width:1px,stroke-dasharray: 6 4;
    classDef note fill:#FCE7F3,stroke:#BE185D,color:#2A0B18,stroke-width:1px;
    classDef artifact fill:#F3F4F6,stroke:#4B5563,color:#111827,stroke-width:1px;
```
