Architecture

MinIO is a single Go binary that boots one HTTP server (and optional FTP/SFTP listeners), routes S3 and admin requests through middleware, and serves data from an erasure-coded backend that may span many drives and nodes. This page traces what happens between main.go and a byte landing on disk.

Top-level layout

Directory	Purpose
main.go	Tiny shim: imports internal/init then calls cmd.Main(os.Args).
cmd/	The server runtime: ~340 production .go files, ~7M of source. All HTTP/S3/admin/erasure logic lives here.
internal/	34 reusable packages (auth, config, crypto, kms, event, grid, http, hash, ...).
docs/	Operational docs, integration guides, and reference shell scripts that double as integration tests.
helm/, helm-releases/	Community Helm chart and release index for Kubernetes installs.
buildscripts/	Build, lint, cross-compile, and end-to-end shell tests invoked by the Makefile.

The CLI bootstraps in cmd/main.go (the Main function) and dispatches to subcommands. The primary command, server, is defined in cmd/server-main.go.

Boot sequence

sequenceDiagram
    participant U as User
    participant M as main.go
    participant CMD as cmd.Main
    participant SRV as serverMain
    participant OBJ as Object layer
    participant HTTP as HTTP server

    U->>M: ./minio server DIR1 [DIR2..]
    M->>CMD: cmd.Main(args)
    CMD->>SRV: dispatch "server"
    SRV->>SRV: parse endpoints (cmd/endpoint.go)
    SRV->>SRV: bootstrap config (cmd/common-main.go)
    SRV->>OBJ: newObjectLayer (erasure server pool)
    OBJ->>OBJ: format drives (cmd/format-erasure.go)
    OBJ->>OBJ: connect peers (cmd/peer-rest-client.go)
    SRV->>HTTP: register routers (cmd/routers.go)
    HTTP->>U: listen on :9000 (and console on :9001)

cmd/server-main.go builds the cluster topology from the directory or URL arguments. The "ellipsis" notation http://node{1...4}/data{1...4} is parsed in cmd/endpoint-ellipses.go and cmd/endpoint.go. cmd/prepare-storage.go waits for a quorum of peers to come up before serving requests.

Request lifecycle

graph LR
    R[HTTP request] --> GH[generic-handlers.go]
    GH --> RTR[mux.Router from routers.go]
    RTR --> AUTH[auth-handler.go]
    AUTH --> SIG[signature-v4.go / signature-v2.go]
    SIG --> H[object-handlers.go / bucket-handlers.go / admin-handlers*.go]
    H --> OBJ[ObjectLayer interface]
    OBJ --> POOL[erasure-server-pool.go]
    POOL --> SET[erasure-sets.go]
    SET --> XL[erasure-object.go]
    XL --> RS[reedsolomon encode/decode]
    XL --> DRV[xl-storage.go on local disk]
    XL --> REST[storage-rest-client.go to peer]

1. Generic middleware (cmd/generic-handlers.go) runs for every request: CORS, request size limits, header normalisation, throttling.
2. Routing. cmd/api-router.go builds the S3 router (/{bucket} and /{bucket}/{object:.+}) using github.com/minio/mux. cmd/admin-router.go mounts the admin REST API at /minio/admin/v3.
3. Authentication. cmd/auth-handler.go figures out the auth type (anonymous, JWT, Sig v2, Sig v4, post-policy, presigned) and validates the signature. STS-issued temporary credentials and JWT cookies for the console are also handled here.
4. Handler. S3 verb handlers (PutObject, ListObjectsV2, CompleteMultipartUpload, …) live in cmd/object-handlers.go, cmd/object-multipart-handlers.go, cmd/bucket-handlers.go, cmd/bucket-listobjects-handlers.go. They translate HTTP into calls on ObjectLayer.
5. Object layer. cmd/object-api-interface.go defines the ObjectLayer interface; cmd/erasure-server-pool.go is the runtime implementation.
6. Server pool → set → drives. A pool (erasure-server-pool.go) is composed of one or more sets (erasure-sets.go); a set is the erasure-coding domain (typically 16 drives). erasure-object.go does the encode/decode using github.com/klauspost/reedsolomon. Local drives go through xl-storage.go; remote drives go through the storage REST client (storage-rest-client.go / storage-rest-server.go).

Persistence model: xl.meta

Every object on disk is one or more shard files plus an xl.meta sidecar that tracks versions, parts, encryption info, healing state, and free versions. The format is defined in cmd/xl-storage-format-v2.go (current) with cmd/xl-storage-format-v1.go and cmd/xl-storage-format-v2-legacy.go kept for backward compatibility.

xl.meta uses MessagePack via github.com/tinylib/msgp; the *_gen.go files in cmd/ are generated by msgp (see go:generate in main.go).

Distribution: peers, locks, grid

• Peer RPC. cmd/peer-rest-server.go and cmd/peer-rest-client.go carry cluster control messages: load policies, broadcast bucket metadata changes, gather metrics.
• Storage RPC. cmd/storage-rest-server.go and cmd/storage-rest-client.go ship raw I/O between nodes that share an erasure set across hosts.
• Distributed locks. cmd/namespace-lock.go is the hot-path API; under the hood it delegates to internal/dsync/ for cluster-wide locks, and to cmd/local-locker.go for in-process locks. The lock-rest server (cmd/lock-rest-server.go) exposes the locker over HTTP.
• Grid. internal/grid/ is a binary multiplex protocol used by newer cluster RPCs (see internal/grid/README.md). It is faster than the storage-rest path for small messages.

Healing, scanning, MRF

• Data scanner (cmd/data-scanner.go) walks every object every few hours, updating data-usage-cache for quotas and lifecycle, and emitting heal hints for bitrot and missing shards.
• Background healing (cmd/global-heal.go, cmd/erasure-healing.go) repairs missing or corrupted shards using the surviving parity.
• MRF — Most Recently Failed (cmd/mrf.go) re-tries operations that failed on a peer once the peer recovers.
• New-disk healing (cmd/background-newdisks-heal-ops.go) detects a fresh drive, formats it, and rebuilds its shards from siblings.

IAM and policy

cmd/iam.go is the single entry point for users/groups/policies. It can be backed by:

• The object store itself (cmd/iam-object-store.go).
• An external etcd cluster (cmd/iam-etcd-store.go).

Policy evaluation uses github.com/minio/pkg/v3/policy (IAM JSON policy), with bucket-policy parsing in cmd/bucket-policy.go. Identity providers (LDAP, OpenID, AssumeRole, certificate) are wired in cmd/sts-handlers.go and internal/config/identity/.

Replication

• Bucket replication. cmd/bucket-replication.go is an asynchronous worker pool that replicates PUTs and DELETEs to a peer S3 endpoint described by a target (cmd/bucket-targets.go).
• Site replication. cmd/site-replication.go keeps multiple MinIO clusters in lock-step: replicating buckets, IAM, lifecycle, encryption, and policies. The configuration root is cmd/admin-handlers-site-replication.go.

Configuration

internal/config/ is a registry-driven config layer where every subsystem registers a help/parse block (see internal/config/notify/, internal/config/identity/, internal/config/ilm/, …). Effective config is loaded via cmd/config-current.go, persisted on the object store, and propagated to peers via the peer REST.

Settings can also come from environment variables (handled by github.com/minio/pkg/v3/env) or a single YAML file (the --config flag, parsed in cmd/server-main.go).

Observability

• Metrics. Two generations live side by side: classic v2 (cmd/metrics-v2.go) and v3 (cmd/metrics-v3*.go) with grouped endpoints under /minio/metrics/v3.
• Audit & logger. internal/logger/ and the audit subsystem in internal/logger/audit/ ship structured events to webhook, console, or Kafka via internal/event/target/.
• Health. cmd/healthcheck-handler.go exposes liveness/readiness on /minio/health/live and /minio/health/ready.

For deeper dives, see Systems and Packages.