Code Organization

Relevant source files

• CREDITS
• cmd/admin-handlers-config-kv.go
• cmd/admin-handlers.go
• cmd/admin-handlers_test.go
• cmd/admin-router.go
• cmd/benchmark-utils_test.go
• cmd/common-main.go
• cmd/config-current.go
• cmd/globals.go
• cmd/main.go
• cmd/notification.go
• cmd/object-api-multipart_test.go
• cmd/object-api-putobject_test.go
• cmd/object-handlers_test.go
• cmd/object_api_suite_test.go
• cmd/peer-rest-client.go
• cmd/peer-rest-common.go
• cmd/peer-rest-server.go
• cmd/server-main.go
• cmd/server-startup-msg.go
• cmd/server-startup-msg_test.go
• cmd/server_test.go
• cmd/test-utils_test.go
• cmd/update-notifier.go
• cmd/update-notifier_test.go
• cmd/utils.go
• cmd/utils_test.go
• go.mod
• go.sum
• internal/config/config.go
• internal/config/constants.go
• main.go

This page documents MinIO's codebase organization, focusing on the package structure, the central cmd/ directory, global variable management in globals.go, subsystem initialization patterns, and the organization of the internal/ package. This guide is intended for developers working with or extending MinIO's codebase.

For information about building from source and compilation, see Building from Source. For testing infrastructure details beyond organization, see Testing Infrastructure.

---

Package Structure Overview

MinIO follows Go's standard project layout with a monolithic repository structure. The codebase is organized into two primary areas:

• cmd/ - Contains the main application code, API handlers, storage layer, and all server functionality
• internal/ - Contains reusable internal packages that provide supporting functionality

Sources: go.mod1-3 main.go1-27 cmd/server-main.go1-18 cmd/globals.go1-18

---

Entry Point and Command Structure

MinIO uses a single entry point with a CLI-based command structure powered by the github.com/minio/cli library.

Main Entry Point

The application entry point is minimal and delegates to the cmd package:

File	Purpose
main.go	Application entry point, imports cmd package
cmd/main.go (not shown but exists)	CLI application setup
cmd/server-main.go	Server command implementation (serverMain function)

Sources: main.go18-27 cmd/server-main.go199-241

Command Line Processing

The serverCmd variable in cmd/server-main.go199-241 defines the server command structure:

• Flags: Defined in ServerFlags at cmd/server-main.go62-197
• Action: Points to serverMain function for execution
• Arguments: Processed via serverCmdArgs() at cmd/server-main.go243-271

Configuration can be provided via:

• Command-line arguments (disk paths/endpoints)
• YAML configuration file (--config flag)
• Environment variables (MINIO_ARGS, MINIO_VOLUMES, MINIO_ENDPOINTS)

Sources: cmd/server-main.go62-271 cmd/common-main.go358-445

---

The cmd/ Package - Core Application Code

The cmd/ package is the heart of MinIO and contains all server functionality in a single package. This design choice simplifies internal communication but results in a large package with many files.

File Organization Patterns

Files in cmd/ follow consistent naming conventions:

Pattern	Purpose	Examples
*-main.go	Entry points and initialization	server-main.go, common-main.go
*-handlers.go	HTTP API handlers	object-handlers.go, admin-handlers.go
*-handlers-*.go	Specialized handlers	admin-handlers-config-kv.go, admin-handlers-users.go
erasure*.go	Erasure coding implementation	erasure.go, erasure-sets.go, erasure-server-pool.go
xl-*.go	Local storage layer	xl-storage.go, xl-storage-disk-id-check.go
*-rest-*.go	REST communication	peer-rest-client.go, peer-rest-server.go, storage-rest-client.go
*_test.go	Unit tests	object-handlers_test.go, utils_test.go
test-*.go	Test utilities	test-utils_test.go

Sources: cmd/server-main.go1-18 cmd/globals.go1-18 cmd/admin-handlers.go1-18 cmd/notification.go1-18 cmd/peer-rest-client.go1-18 cmd/peer-rest-server.go1-18

---

Global State Management

MinIO uses a centralized global state management pattern, with all global variables defined in globals.go.

The globals.go File

cmd/globals.go1-565 defines all global variables used throughout the application. This centralization makes it easy to understand system-wide state but requires careful synchronization.

Key Global Variable Categories

Global Initialization Pattern

Global variables are typically initialized in phases:

1. Package init() - cmd/common-main.go73-116 sets up basic state
2. handleCommonArgs() - cmd/common-main.go447-565 processes CLI arguments and initializes paths
3. serverHandleCmdArgs() - cmd/server-main.go373-448 sets up server-specific globals
4. initAllSubsystems() - cmd/server-main.go450-504 initializes all subsystems

Sources: cmd/globals.go175-565 cmd/common-main.go73-116 cmd/common-main.go447-565 cmd/server-main.go373-448 cmd/server-main.go450-504

Thread Safety Considerations

Many global subsystems use internal synchronization:

• *IAMSys uses locks for cache access
• *NotificationSys coordinates via NotificationGroup
• globalGrid uses atomic.Pointer for lazy initialization

Sources: cmd/globals.go227-289 cmd/notification.go48-152

---

Subsystem Initialization Pattern

MinIO follows a consistent pattern for initializing subsystems. All subsystems implement similar lifecycle methods and are initialized from a central location.

Initialization Flow

Sources: cmd/server-main.go450-504 cmd/server-main.go585-624 cmd/server-main.go626-644

Common Subsystem Structure

Most subsystems follow this pattern:

Component	Purpose	Example
Type definition	Struct holding subsystem state	type IAMSys struct { ... }
Constructor	New*() function returning initialized instance	func NewIAMSys() *IAMSys
Init() method	Loads persistent state from storage	func (sys *IAMSys) Init(ctx, obj, ...)
Operation methods	Public API for subsystem functionality	func (sys *IAMSys) LoadUser(...)

Example from IAMSys:

• Type: cmd/iam.go87-117 (referenced, not shown in files)
• Constructor: Creates instance with empty cache
• Init: Loads users, policies from object store
• Operations: LoadUser(), DeleteUser(), IsAllowed()

Subsystem Notification Pattern

When a subsystem's state changes on one node, it notifies all peers via NotificationSys:

Sources: cmd/notification.go48-194 cmd/notification.go196-226

---

The internal/ Package

The internal/ package contains reusable libraries that support the main application. These packages cannot be imported by external projects (enforced by Go's module system).

Key internal/ Subpackages

Sources: go.mod1-3 internal/config/config.go1-18 internal/config/constants.go1-18

internal/config Structure

The config package is organized by subsystem:

Subpackage	Purpose	Global Variable
config/api	API throttling, CORS	globalAPIConfig
config/compress	Compression settings	globalCompressConfig
config/dns	DNS-based federation	globalDNSConfig
config/identity/ldap	LDAP authentication	Part of globalIAMSys
config/identity/openid	OpenID Connect	Part of globalIAMSys
config/notify	Event notification targets	globalEventNotifier
config/storageclass	Storage class settings	globalStorageClass

Each subpackage typically provides:

• DefaultKVS - Default key-value configuration
• HelpKVS - Help documentation for config keys
• LookupConfig() - Parse configuration from KV store
• Validation functions

Sources: internal/config/config.go1-560 cmd/config-current.go58-109

Initialization Registration

Subsystems register their configuration during init():

cmd/config-current.go58-109 shows the initHelp() function that registers all subsystem defaults and help text with the config system.

Sources: cmd/config-current.go58-109

---

Testing Infrastructure

MinIO has extensive test utilities organized to support both unit and integration tests.

Test File Organization

File	Purpose
test-utils_test.go	Core test utilities and helpers
*_test.go	Unit tests for specific functionality
Test setup functions	prepareFS(), prepareErasure(), etc.

Test Utilities Structure

Sources: cmd/test-utils_test.go72-125 cmd/test-utils_test.go190-241 cmd/test-utils_test.go314-396

Backend Preparation Functions

Test backends are initialized via these functions:

• prepareFS(ctx) - cmd/test-utils_test.go190-205 - Creates single-disk filesystem backend
• prepareErasure(ctx, nDisks) - cmd/test-utils_test.go211-241 - Creates N-disk erasure backend with disk health checks
• prepareErasure16(ctx) - cmd/test-utils_test.go243-245 - 16-disk variant
• prepareErasureSets32(ctx) - cmd/test-utils_test.go207-209 - 32-disk variant

Test Execution Pattern

This pattern allows tests to run against multiple storage backends (FS, Erasure, Erasure Sets) without duplication.

Sources: cmd/test-utils_test.go397-485 cmd/object-handlers_test.go64-78

---

Key Conventions and Patterns

File Naming Conventions

MinIO follows strict file naming patterns in the cmd/ package:

Convention	Meaning	Example
*-main.go	Entry point or initialization	server-main.go
*-handlers.go	HTTP handler functions	object-handlers.go
*-rest-*.go	REST client/server	peer-rest-client.go
*-interface.go	Interface definitions	object-api-interface.go
globals.go	Global variable definitions	globals.go
utils.go	General utility functions	utils.go

Error Handling Pattern

MinIO uses a consistent error handling approach:

1. Define custom error types for domain-specific errors
2. Use errors.Is() and errors.As() for error checking
3. Log errors with context via logger package
4. Return structured errors via toAPIErr() functions

Example error types:

• BucketNotFound{Bucket string}
• ObjectNotFound{Bucket, Object, VersionID string}
• InsufficientReadQuorum{}
• BackendDown{Err string}

Sources: cmd/utils.go82-183

Context Propagation

All operations receive a context.Context as the first parameter:

• Enables cancellation and timeout
• Carries request-scoped values (ReqInfo, logger tags)
• Passed through entire call chain from HTTP handler to disk I/O

Logging Patterns

MinIO uses specialized logging functions:

Function	Purpose
logger.LogIf(ctx, err)	Log if error is non-nil
logger.CriticalIf(ctx, err)	Log critical errors
adminLogIf(ctx, err)	Log admin-related errors
peersLogOnceIf(ctx, err, id)	Log peer errors once per ID

Sources: cmd/utils.go1-70 cmd/admin-handlers.go180-206

RPC/Grid Communication

Inter-node communication uses two systems:

1. Legacy REST - peer-rest-client.go, peer-rest-server.go
2. Grid RPC - Modern binary protocol via internal/grid

Grid handlers are registered globally:

• Request-response: grid.NewSingleHandler<FileRef file-url="https://github.com/minio/minio/blob/7aac2a2c/Req, Resp" undefined file-path="Req, Resp">Hii</FileRef>
• Streaming: grid.NewStream<FileRef file-url="https://github.com/minio/minio/blob/7aac2a2c/Payload" undefined file-path="Payload">Hii</FileRef>
• All handlers defined in cmd/peer-rest-server.go54-104

Sources: cmd/peer-rest-server.go50-104 cmd/peer-rest-client.go43-106

---

Summary

MinIO's code organization reflects its evolution from a simpler system to a complex, distributed object storage server:

• Single Package Design: Most code lives in cmd/, enabling close integration but requiring careful organization
• Global State Management: Centralized in globals.go, initialized in phases during startup
• Subsystem Pattern: Consistent structure for IAM, configuration, notification, and other subsystems
• Internal Libraries: Reusable packages in internal/ provide supporting functionality
• Testing Infrastructure: Comprehensive utilities support testing against multiple backend configurations
• Naming Conventions: Strict file naming patterns make navigation easier despite package size

Understanding these patterns is essential for navigating the codebase and contributing to MinIO.

Sources: cmd/server-main.go1-872 cmd/globals.go1-565 cmd/common-main.go1-1184 cmd/test-utils_test.go1-3500 internal/config/config.go1-560