# hallotschuess/very-simple-upload-server architecture

> Architecture diagram of the GitHub repository hallotschuess/very-simple-upload-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hallotschuess/very-simple-upload-server
- Repository: https://github.com/hallotschuess/very-simple-upload-server

## Overview

Summary (project type & purpose)
- This is a minimal single-binary HTTP upload server written in Go. It exposes GET, PUT and DELETE over HTTP, uses an on-disk directory as its storage root, and is distributed as Docker images (standard and alpine). The runtime is configured via environment variables (tokens, root dir, base path, logging etc.). The codebase is intentionally tiny: main.go is the entrypoint and build/ contains Dockerfiles.

- Server as a lightweight containerized HTTP service that accepts client requests (browser/cli/other services), authorizes them (token via query or header), performs file operations (temp write → digest check → atomic rename for PUT, read for GET, recursive delete for DELETE), and persists data to a mounted host volume. Also show optional external responsibilities typically used in production (reverse proxy / TLS termination, load balancer, monitoring / logging agents).

##### Main components
- External clients
- curl / browser / other HTTP clients
- Network ingress / edge (optional, depending on deployment)
- Reverse proxy (nginx/traefik) or LB for TLS, host port mapping (Docker -p)
- Docker container / Process
- Go HTTP server (main binary) — label main.go as entrypoint
- HTTP router / URL base path handling
- Auth layer (token lookup: TOKEN_PUT / TOKEN_GET / TOKEN_DELETE; AUTH_HEADER + AUTH_HEADER_PREFIX; query param precedence)
- Upload handler (PUT):
- Accept formfile key "file" or raw body
- Create temporary file in same directory
- Digest verification (Digest header: md5, sha-256)
- Atomic replace (move/rename) to destination
- Download handler (GET): read file, stream to client
- Delete handler (DELETE): delete file or recursively remove directory, remove empty dirs
- CORS handling (always Access-Control-Allow-Origin: *)
- Logging subsystem (stdout; configurable format via LOG_FORMAT)
- Config via environment variables (LISTEN, ROOT_DIR, URL_BASE_PATH, DEBUG, FORCE_DIGEST, tokens, etc.)
- Persistent storage
- Mounted volume or host directory (Docker -v /uploads)
- Filesystem semantics (temp files in same dir; atomic rename)
- Build / Image artifacts
- build/Dockerfile(s) → image tags (latest, alpine, version)
- Optional external systems (if used in production)
- Volume provider (host disk, network storage)
- Monitoring / log aggregator (Fluentd / Elasticsearch / Prometheus exporters)
- Secrets manager (if tokens are placed securely instead of env)
- Backup / snapshot system

##### Important architectural patterns & design traits
- Single-process, single-binary service (no internal microservices)
- Filesystem-backed storage (no external DB)
- Token-based per-method authorization (stateless auth using environment-provided tokens)
- Atomic file operations: write to temp file then rename (lower risk of partial writes)
- Config-by-env (12-factor friendly), outputs logs to stdout (suitable for containerized log ingestion)
- Small surface area makes it suitable to be placed behind edge components for TLS and auth hardening.

- Go runtime / main.go (entry point)
- Docker images and Dockerfiles (build/Dockerfile and build/alpine.Dockerfile)
- Environment variables mapping (list the important ones: TOKEN_*, ROOT_DIR, URL_BASE_PATH, LISTEN, AUTH_HEADER, AUTH_HEADER_PREFIX, FORCE_DIGEST)
- Persistent volume mount (name example: my_volume:/uploads)
- HTTP (port 80) exposed by container
- Digest header support: md5 & sha-256

- C4 suggestion: Level 1 (system context): show clients, the upload server, storage, and optional ingress. Level 2 (container/component): show the internal components outlined above.

##### Detail to capture (do not omit)
- The temp file behavior and atomic rename (important for correctness)
- Which sources of token are supported and precedence (query param wins over header)
- That the server always sets Access-Control-Allow-Origin: *
- The environment variables that change behavior (base path, listen address, digest enforcement)
- Docker image variants and the approximate build path (source → build → image tag)
- Where logs go (stdout and format selection)
- That filename itself is irrelevant; only URL path determines storage location

- [ ] Show clients and ingress
- [ ] Show container with internal components (router, auth, handlers, digest checker)
- [ ] Show persistent volume with mount path
- [ ] Show env vars / config influencing behavior
- [ ] Show build artifacts (Dockerfile → image)
- [ ] Include a short sequence for PUT (temp-write → validate → rename) and mention cleanup on error

Minimal text to annotate directly from the repo
- Entrypoint: main.go
- Dockerfiles: build/Dockerfile, build/alpine.Dockerfile
- Config-by-env: TOKEN_GET/TOKEN_PUT/TOKEN_DELETE, ROOT_DIR, URL_BASE_PATH, AUTH_HEADER, AUTH_HEADER_PREFIX, LISTEN, FORCE_DIGEST
- Runtime behavior: Accepts formfile "file" or request body; uses URL path as storage key; overwrites existing files; supports Digest header; always returns CORS header.

Final advice

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External clients
    subgraph "Clients" 
        direction TB
        Browser["Browser / SPA / Web UI"]:::external
        CLI["curl / CLI / other HTTP clients"]:::external
        OtherServices["Other services (HTTP clients)"]:::external
    end

    %% Optional network ingress / edge
    ReverseProxy["Reverse Proxy / LB (nginx/traefik)"]:::edge
    Browser -->|"HTTP (PUT/GET/DELETE)"| ReverseProxy
    CLI -->|"HTTP (PUT/GET/DELETE)"| ReverseProxy
    OtherServices -->|"HTTP (PUT/GET/DELETE)"| ReverseProxy

    %% Container
    subgraph "Container: very-simple-upload-server (Docker)" 
        direction TB
        ContainerProcess["Go single-binary process"]:::container
        Entrypoint["main.go (entrypoint)"]:::file
        Router["HTTP Router / URL base path handling"]:::component
        Auth["Auth Layer\n(TOKEN_PUT,TOKEN_GET,TOKEN_DELETE)\nHeader or query (query takes precedence)"]:::component
        CORS["CORS Handler\nAccess-Control-Allow-Origin: *"]:::component
        Logging["Logging -> stdout\n(LOG_FORMAT, DEBUG)"]:::component
        ConfigEnv["Config (env vars)\nLISTEN,ROOT_DIR,URL_BASE_PATH,AUTH_HEADER,AUTH_HEADER_PREFIX,FORCE_DIGEST,..."]:::config

        subgraph "Handlers"
            direction TB
            PUT["PUT Handler\n(formfile 'file' or raw body)"]:::handler
            Digest["Digest Verifier\n(Digest header: md5, sha-256)\nFORCE_DIGEST enforcement"]:::component
            TempFile["Temp File Writer\ncreate temp in same dir; cleanup on error"]:::component
            AtomicRename["Atomic Replace\nrename/move to destination"]:::component
            GET["GET Handler\nread & stream file"]:::handler
            DELETE["DELETE Handler\ndelete file or recursive dir; cleanup empty dirs"]:::handler
        end

        ContainerProcess --> Entrypoint
        Entrypoint --> Router
        Router --> CORS
        CORS --> Auth
        Auth --> PUT
        Auth --> GET
        Auth --> DELETE

        PUT --> TempFile
        TempFile --> Digest
        Digest --> AtomicRename
        AtomicRename --> StorageAdapter["Storage Adapter\n(filesystem operations)"]:::component

        GET --> StorageAdapter
        DELETE --> StorageAdapter

        ContainerProcess --> Logging
        ConfigEnv --> ContainerProcess
    end

    %% Persistent storage
    Storage["Host Volume /uploads\n(my_volume:/uploads)"]:::storage
    StorageAdapter -->|"write/read/delete (fs semantics)"| Storage

    %% Docker build artifacts
    subgraph "Build / Image"
        direction TB
        SourceCode["Source: main.go, go.mod, go.sum, README.md, LICENSE"]:::code
        DockerfileStd["build/Dockerfile (standard)"]:::file
        DockerfileAlpine["build/alpine.Dockerfile (alpine)"]:::file
        Image["Docker Image tags\nhallotschuess/very-simple-upload-server:latest,alpine,vX.Y"]:::artifact
    end

    SourceCode --> DockerfileStd
    SourceCode --> DockerfileAlpine
    DockerfileStd --> Image
    DockerfileAlpine --> Image
    Image -->|"docker run -v my_volume:/uploads -p 80:80"| ContainerProcess

    %% Optional external systems
    Secrets["Secrets Manager (optional)\nstore tokens securely"]:::optional
    Monitoring["Monitoring / Log Aggregator\nPrometheus / Fluentd / ELK"]:::optional
    Backup["Backup / Snapshot System (optional)"]:::optional
    VolumeProvider["Volume Provider (host disk / NFS)"]:::optional

    Secrets -.-> ContainerProcess
    Monitoring -.-> Logging
    Storage -.-> VolumeProvider
    Backup -.-> Storage

    %% PUT sequence detail (side sequence)
    subgraph "PUT Sequence (detailed)" 
        direction TB
        Req["Client PUT /{path} + token [+ Digest header]"]:::seq
        AuthCheck["Auth: validate TOKEN_PUT\n(query param wins over header)"]:::seq
        WriteTemp["Write temp file in same dir"]:::seq
        ValidateDigest["If Digest provided or FORCE_DIGEST: verify digest"]:::seq
        Rename["Atomic rename -> final path (overwrite)"]:::seq
        Response["200/201 or error (temp cleaned on error)"]:::seq

        Req --> AuthCheck
        AuthCheck --> WriteTemp
        WriteTemp --> ValidateDigest
        ValidateDigest --> Rename
        Rename --> Response
        Response --> Req
    end

    %% Connections from main flow to PUT sequence
    CLI -->|"PUT /{path}"| AuthCheck
    Auth -->|"for PUT flows"| AuthCheck
    AuthCheck -->|"on success"| WriteTemp

    %% Security callout
    SecurityNote["Security Notes\n- Tokens are simple bearer tokens (env)\n- CORS is permissive (Access-Control-Allow-Origin: *)\n- Put behind TLS or reverse proxy in production"]:::warning
    SecurityNote -.-> Auth
    SecurityNote -.-> CORS

    %% Legend
    subgraph "Legend" 
        direction TB
        L1["External Actor"]:::external
        L2["Edge / Ingress"]:::edge
        L3["Container / Process"]:::container
        L4["Internal Component"]:::component
        L5["Handler"]:::handler
        L6["Persistent Storage"]:::storage
        L7["Config / Secrets"]:::config
        L8["Build Artifacts / Files"]:::file
        L9["Optional / External"]:::optional
        L10["Security Callout"]:::warning
    end

    %% Click events for mapped components (paths from component_mapping)
    click Entrypoint "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click Router "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click Auth "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click PUT "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click GET "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click DELETE "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click CORS "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click Digest "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click Logging "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click ConfigEnv "https://github.com/hallotschuess/very-simple-upload-server/blob/master/main.go"
    click DockerfileStd "https://github.com/hallotschuess/very-simple-upload-server/tree/master/build/Dockerfile"
    click DockerfileAlpine "https://github.com/hallotschuess/very-simple-upload-server/blob/master/build/alpine.Dockerfile"
    click SourceCode "https://github.com/hallotschuess/very-simple-upload-server/blob/master/go.mod"
    click SourceCode "https://github.com/hallotschuess/very-simple-upload-server/blob/master/go.sum"
    click SourceCode "https://github.com/hallotschuess/very-simple-upload-server/blob/master/README.md"
    click SourceCode "https://github.com/hallotschuess/very-simple-upload-server/tree/master/LICENSE"

    %% Styles
    classDef external fill:#E6F2FF,stroke:#2B6CB0,color:#03396c,stroke-width:1px,shape:rounded;
    classDef edge fill:#E8F8F5,stroke:#16A085,color:#0B5345,stroke-width:1px,shape:rounded;
    classDef container fill:#EAFFE8,stroke:#1E7A1E,color:#0B6623,stroke-width:1px;
    classDef component fill:#F0FFF4,stroke:#28A745,color:#0B6623,stroke-width:1px;
    classDef handler fill:#F7FFF8,stroke:#2ECC71,color:#0B6623,stroke-width:1px;
    classDef storage fill:#F2F2F2,stroke:#95A5A6,color:#566573,stroke-width:1px,stroke-dasharray: 5 2;
    classDef config fill:#FFF3E0,stroke:#FFA726,color:#8A4B00,stroke-width:1px,shape:rounded;
    classDef file fill:#F4F6F8,stroke:#6C7A89,color:#2C3E50,stroke-width:1px,shape:rounded;
    classDef artifact fill:#EEF8FF,stroke:#3498DB,color:#0B516B,stroke-width:1px,shape:rounded;
    classDef optional fill:#FEF9E7,stroke:#F1C40F,color:#7A4B00,stroke-width:1px,shape:rounded;
    classDef warning fill:#FFF1F0,stroke:#E74C3C,color:#C0392B,stroke-width:1px,shape:rounded;
    classDef seq fill:#FFFFFF,stroke:#BDC3C7,color:#2C3E50,stroke-width:1px;
    classDef code fill:#F8FBFF,stroke:#5DADE2,color:#1B4F72,stroke-width:1px,shape:rounded;

    class Browser,CLI,OtherServices external
    class ReverseProxy edge
    class ContainerProcess container
    class Entrypoint,DockerfileStd,DockerfileAlpine file
    class Router,Auth,CORS,Logging,StorageAdapter,Digest,TempFile,AtomicRename component
    class PUT,GET,DELETE handler
    class Storage storage
    class ConfigEnv config
    class SourceCode code
    class Image artifact
    class Secrets,Monitoring,Backup,VolumeProvider optional
    class SecurityNote warning
    class Req,AuthCheck,WriteTemp,ValidateDigest,Rename,Response seq
```
