Core Application Architecture

Relevant source files

This page documents the fundamental architecture of fastfetch, focusing on the global state management (FFinstance), the application lifecycle, and the layered system design that enables extensibility and cross-platform support. It also explains the module registry and how the core orchestrates detection, configuration, and output.

For details on specific subsystems, see:

[2.1] Application Lifecycle and Entry Points
[2.2] Module System Architecture
[2.3] Configuration and Schema System

Global State Management: The `FFinstance` Singleton

Fastfetch maintains all global configuration and runtime state in a single global variable, instance, of type FFinstance. This singleton is defined in src/common/init.c20 and declared in src/fastfetch.h56 It is accessible throughout the codebase and is the central point for all stateful operations.

Core Data Structures

Key Structure Fields

Structure	Field	Type	Purpose / Notes	Defined At
FFinstance	config	FFconfig	User configuration (logo, display, general)	src/fastfetch.h53
FFinstance	state	FFstate	Runtime state (platform, buffers, docs)	src/fastfetch.h54
FFconfig	logo	FFOptionsLogo	Logo options	src/fastfetch.h31
FFconfig	display	FFOptionsDisplay	Output/display options	src/fastfetch.h32
FFconfig	general	FFOptionsGeneral	General options (threading, modules, etc)	src/fastfetch.h33
FFstate	platform	FFPlatform	Platform paths and metadata	src/fastfetch.h44
FFstate	configDoc	yyjson_doc*	Parsed config JSON document	src/fastfetch.h45
FFstate	resultDoc	yyjson_mut_doc*	Output JSON document (if JSON output enabled)	src/fastfetch.h46
FFstate	genConfigPath	FFstrbuf	Path for generated config file	src/fastfetch.h47
FFstate	fullConfig	bool	Whether to generate full config	src/fastfetch.h48

Initialization Sequence

The singleton is initialized by ffInitInstance() (src/common/init.c49-61), which performs:

Locale setup (setlocale) for UTF-8 and time formatting (src/common/init.c52-57)
State zero-initialization and platform path detection via initState() (src/common/init.c22-40)
Default configuration setup via defaultConfig() (src/common/init.c42-47)

Sources: src/fastfetch.h29-55 src/common/init.c20-61 src/options/logo.c src/options/display.c src/options/general.c

Application Lifecycle

Fastfetch follows a strict lifecycle: initialization, configuration, execution, and cleanup. This is managed by a set of core functions and a global state.

Diagram: "Core Execution Flow (Code Entities and Sequence)"

Lifecycle Phases

Initialization: ffInitInstance() (src/common/init.c49-61) sets up locale, platform paths, and default config.
Configuration: parseCommand() and parseOption() (src/fastfetch.c572-880) parse CLI arguments, load config files, and update instance.config.
Execution: ffStart() (src/common/init.c97-134) prepares the terminal, prints the logo, and then modules are executed in order.
Cleanup: ffFinish() (src/common/init.c136-142) restores terminal state. ffDestroyInstance() (src/common/init.c159-163) frees all resources.

Module Execution Patterns

Registry-driven (main fastfetch): Modules are looked up in ffModuleInfos and executed in order as specified by config or CLI (src/fastfetch.c686-794).
Direct (flashfetch): Modules are called directly in code (src/flashfetch.c22-137).

Sources: src/common/init.c49-163 src/fastfetch.c572-880 src/flashfetch.c22-137

Layered System Architecture

Fastfetch is organized into conceptual layers, each with a clear responsibility. This enables separation of concerns, platform abstraction, and extensibility.

Diagram: "Layered Architecture and Code Entities"

Layer Responsibilities

Layer	Main Code Entities / Files	Responsibility
User Input	`parseCommand()`, `parseOption()`	Parse CLI, config files, environment
Core	`FFinstance`, `ffModuleInfos`, format	Orchestrate state, module registry, formatting
Detection	`ffDetect*()` in detection modules	Gather system/hardware/software info
Platform	`_linux.c`, `_windows.c`, ...	Platform-specific implementations
Presentation	`ffLogoPrint()`, `ffPrintLogoAndKey()`	Output, logo, color, formatting

Sources: src/fastfetch.c src/common/init.c src/common/modules.c src/common/format.c src/detection/cpu/cpu.c src/detection/gpu/gpu.c src/detection/disk/disk.c src/detection/terminalshell/terminalshell.c src/detection/packages/packages.c src/logo/logo.c src/common/printing.c src/common/color.h CMakeLists.txt

Module Registry System

Fastfetch uses a registry-based architecture to manage its 70+ modules. Modules are self-contained plugins that register their metadata in compile-time arrays.

Module Organization

Registry Structure

The global ffModuleInfos array (src/fastfetch.h57) is a 26-element array where each element points to a NULL-terminated array of module pointers. Modules are grouped by their first letter (A-Z) for efficient lookup.

Example module lookup (pseudocode based on src/fastfetch.c26-55):

Sources: src/fastfetch.h57 src/fastfetch.c26-55

Module Metadata Structure

Each module defines an FFModuleBaseInfo structure containing:

Field	Type	Purpose
`name`	`const char*`	Module identifier (e.g., "CPU", "GPU")
`description`	`const char*`	Human-readable description
`formatArgs`	`FFModuleFormatArgs`	Array of format placeholder definitions
Function Pointers	Various	Module lifecycle hooks

Module Lifecycle Function Pointers:

Format Arguments

The formatArgs field defines available placeholders for the module's custom format string. For example, the CPU module (src/fastfetch.c40-45) defines:

{name}: CPU model name
{vendor}: CPU vendor
{cores}: Core count
{freq}: Current frequency
etc.

These are used by the format engine (src/common/format.c) to substitute placeholders in user-specified format strings.

Sources: src/fastfetch.c26-88 src/common/format.c

Module Registration Pattern

Modules register via static FFModuleBaseInfo structures. The logo system src/logo/builtin.c13-732 demonstrates the NULL-terminated array pattern:

Detection modules follow the same pattern. The CMake build system CMakeLists.txt365-500 compiles all module files into LIBFASTFETCH_SRC:

Module File	Defines	Exports
src/modules/cpu/cpu.c	`FFCPUOptions`, `ffPrintCPU()`	`FFModuleBaseInfo ffModuleCPU`
src/modules/gpu/gpu.c	`FFGPUOptions`, `ffPrintGPU()`	`FFModuleBaseInfo ffModuleGPU`
src/modules/disk/disk.c	`FFDiskOptions`, `ffPrintDisk()`	`FFModuleBaseInfo ffModuleDisk`

The registry arrays src/common/modules.c aggregate these module definitions:

ffModuleInfos[2] → C modules (CPU, Colors, Cursor, etc.)
ffModuleInfos[3] → D modules (Disk, Display, DE, etc.)

Sources: src/logo/builtin.c13-732 CMakeLists.txt365-500 src/common/modules.c

Summary Table: Key Architecture Components

Component	Type	Location	Purpose
`FFinstance`	Global singleton	src/common/init.c20	Central state container
`FFconfig`	Struct	src/fastfetch.h29-34	User configuration
`FFstate`	Struct	src/fastfetch.h36-49	Runtime state
`ffModuleInfos`	Module registry	src/fastfetch.h57	26 arrays of module pointers (A-Z)
`FFModuleBaseInfo`	Module metadata	Referenced in src/fastfetch.c30	Module name, description, lifecycle hooks
`ffInitInstance()`	Initialization	src/common/init.c49	Initialize global state
`ffStart()`	Setup	src/common/init.c97	Prepare console, print logo
`ffFinish()`	Cleanup	src/common/init.c136	Restore terminal state
`ffDestroyInstance()`	Teardown	src/common/init.c159	Free all resources
`parseJsoncFile()`	Config parser	src/common/jsonconfig.c381	Load JSONC/JSON5 files
`ffParseFormatString()`	Format engine	src/common/format.c	Substitute placeholders
`ffPrintLogoAndKey()`	Output	src/common/printing.c	Synchronize logo and text printing

Sources: All locations cited in table cells above