{
  # ==============================================================================
  # FLAKE DESCRIPTION
  # ==============================================================================
  # Main flake that defines bertof's system configurations
  description = "bertof's system configuration";

  # ==============================================================================
  # INPUTS - EXTERNAL DEPENDENCIES
  # ==============================================================================
  inputs = {
    # Backward compatibility for non-flake systems
    flake-compat.url = "https://flakehub.com/f/edolstra/flake-compat/1.tar.gz";

    # Nixpkgs channels
    # Stable channel (release 25.05) for production systems
    nixpkgs-s.url = "github:NixOS/nixpkgs/release-25.11";
    # Unstable channel for development and latest packages
    nixpkgs-u.url = "github:NixOS/nixpkgs/nixos-unstable";
    # Default to unstable for most packages
    nixpkgs.follows = "nixpkgs-u";

    # Home Manager for user-level configuration
    # Stable version aligned with stable nixpkgs
    home-manager-s = { url = "github:nix-community/home-manager/release-25.11"; inputs.nixpkgs.follows = "nixpkgs-s"; };
    # Unstable version aligned with unstable nixpkgs
    home-manager-u = { url = "github:nix-community/home-manager"; inputs.nixpkgs.follows = "nixpkgs-u"; };

    # Secret management - using ragenix as alternative to agenix
    # agenix.url = "github:ryantm/agenix";  # Original agenix (commented out)
    ragenix = { url = "github:yaxitech/ragenix"; inputs.nixpkgs.follows = "nixpkgs"; };

    # Desktop environment theming and rice configuration
    nix-rice = { url = "github:bertof/nix-rice/modules"; inputs.nixpkgs.follows = "nixpkgs"; };

    # Generate NixOS system images (ISO, VM, etc.)
    nixos-generators = { url = "github:nix-community/nixos-generators"; inputs.nixpkgs.follows = "nixpkgs"; };

    # Hardware-specific configurations for various devices
    nixos-hardware.url = "github:NixOS/nixos-hardware";

    # Package index for discovering nixpkgs packages
    nix-index-database.url = "github:nix-community/nix-index-database";
    nix-index-database.inputs.nixpkgs.follows = "nixpkgs-u";

    # Support for multiple system architectures
    systems.url = "github:nix-systems/default";

    # Flake parts for modular flake structure
    flake-parts.url = "github:hercules-ci/flake-parts";

    # Git pre-commit hooks for code quality
    git-hooks = { url = "github:cachix/git-hooks.nix"; inputs.nixpkgs.follows = "nixpkgs"; };

    # TODO: Additional tools to evaluate
    # agenix-shell.url = "github:aciceri/agenix-shell"; # TODO
    # agenix-rekey.url = "github:oddlama/agenix-rekey"; # TODO
    # emanote.url = "github:srid/emanote";
  };

  # ==============================================================================
  # OUTPUTS - MAIN FLAKE DEFINITION
  # ==============================================================================
  outputs = { self, ... }@inputs:
    # Common Nix configuration for all systems
    let
      nix-config = {
        allowUnfree = true; # Allow proprietary packages
        extraOptions = "experimental-features = nix-command flakes"; # Enable experimental features
        permittedInsecurePackages = [ ]; # No insecure packages allowed
      };
    in
    # Use flake-parts for modular structure
    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
      # Support all systems defined in inputs.systems
      systems = import inputs.systems;
      imports = [ inputs.git-hooks.flakeModule ];

      # Per-system configuration (applies to each system independently)
      perSystem = { config, pkgs, system, ... }: {
        # Import nixpkgs with custom configuration
        _module.args.pkgs = import inputs.nixpkgs {
          inherit system;
          config = nix-config;
          overlays = [
            inputs.self.overlays.packages
            inputs.self.overlays.overrides
          ];
        };

        # Pre-commit hooks configuration
        pre-commit.settings.hooks = {
          deadnix.enable = true; # Remove dead code from Nix expressions
          nixpkgs-fmt.enable = true; # Format Nix code
          statix.enable = true; # Lint Nix code for best practices
          flake-checker.enable = true;

          # Markdown
          mdformat.enable = true;
          markdownlint.enable = true;

          # Typo
          typos.enable = true;
        };

        # Default development shell
        devShells.default = pkgs.mkShellNoCC {
          inputsFrom = [ config.pre-commit.devShell ]; # Include pre-commit tools
          LOCAL_KEY = "/etc/nix/key"; # Local signing key path
        };

        # Code formatter
        formatter = pkgs.nixpkgs-fmt;

        # Package definitions
        packages = {
          # Export custom packages
          inherit
            (pkgs)
            keyboard-switch
            rbw-fzf
            wl-clipedit
            wl-lockscreen
            wl-update-background
            ;

          # ====================================================================
          # SYSTEM IMAGES FOR DEPLOYMENT
          # ====================================================================

          # Installer ISO for bootstrapping new systems
          install-iso = inputs.nixos-generators.nixosGenerate {
            inherit system;
            modules = [ self.nixosModules.installerModules ];
            format = "install-iso";
          };

          # RAW base image for container/virtualization platforms
          raw-base-image = inputs.nixos-generators.nixosGenerate {
            inherit system;
            modules = [ self.nixosModules.installerModules ];
            format = "raw-efi";
          };

          # VMDK base image for VMware platforms
          vmdk-base-image = inputs.nixos-generators.nixosGenerate {
            system = "x86_64-linux";
            modules = [ self.nixosModules.installerModules ];
            format = "vmware";
          };

          # Aarch64 base image for ARM64 systems (e.g., Raspberry Pi)
          aarch64-base-image = inputs.nixos-generators.nixosGenerate {
            system = "aarch64-linux";
            modules = [ self.nixosModules.installerModules ];
            format = "sd-aarch64";
          };

          # DigitalOcean custom image
          do-image = inputs.nixos-generators.nixosGenerate {
            inherit system;
            modules = [ self.nixosModules.installerModules ];
            format = "do";
          };
        };
      };

      # ========================================================================
      # FLAKE OUTPUTS - SHARED RESOURCES
      # ========================================================================
      flake = {
        # ====================================================================
        # OVERLAYS - CUSTOM PACKAGE OVERRIDES
        # ====================================================================
        overlays = {
          default = inputs.self.overlays.packages;

          # Custom packages defined in this repository
          packages = self: _super: {
            keyboard-switch = self.callPackage ./pkgs/keyboard-switch { };
            wl-clipedit = self.callPackage ./pkgs/wl-clipedit { };
            rbw-fzf = self.callPackage ./pkgs/rbw-fzf { };
            wl-lockscreen = self.callPackage ./pkgs/wl-lockscreen { };
            wl-update-background = self.callPackage ./pkgs/wl-update-background { };
          };

          # Overrides for existing packages
          overrides = _self: super: {
            # Browser configurations with specific flags
            google-chrome = super.google-chrome.override {
              commandLineArgs = [ "--password-store=gnome" "--force-dark-mode" ];
            };
            brave = super.brave.override {
              commandLineArgs = "--ozone-platform=wayland --enable-features=UseOzonePlatform,WebRTCPipeWireCapturer";
            };

            # Custom Home Assistant component (SmartIR) with patched codes
            smartir-zha = super.home-assistant-custom-components.smartir.overrideAttrs (_attr: rec {
              version = "04ac27e";
              src = super.fetchFromGitHub {
                owner = "bertof";
                repo = "SmartIR";
                rev = "6f8cac1";
                hash = "sha256-5Ulb3z46bfIzztHTMNg/Vc26ru9K40242AsW37TLE18=";
              };
              code = super.fetchurl {
                url = "https://gist.githubusercontent.com/bertof/d2a4af6243300b9ba05638af9a29fa6d/raw/6dbb21db986db15f69bb3040585419a270693289/50.json";
                sha256 = "sha256-9564yMudzY8Z9RzvLqJxuV4k6PLBVJdph71BOz6OXRc=";
              };

              patcher = super.fetchurl {
                url = "https://gist.githubusercontent.com/svyatogor/7839d00303998a9fa37eb48494dd680f/raw/66cba20e653f84aab0b9a31ea5b9ca497d038d8a/broadlink_to_tuya.py";
                sha256 = "0m5fbfvsq8sxm0ghs8al8b6z4vfycqkr90qb10w9c4ryag2flnsh";
              };

              postPatch = ''
                ${super.python312}/bin/python3 ${patcher} codes/climate/1946.json > codes/climate/50.json
                # sed 's/Broadlink/MQTT/' codes/climate/1946.json > codes/climate/50.json
                # cp ${code} codes/climate/50.json
              '';
            });

            # libfprint override for compatibility (can be removed when PR merged)
            # Reference: https://github.com/NixOS/nixpkgs/pull/389711
            libfprint = super.libfprint.overrideAttrs (oldAttrs: {
              buildInputs = oldAttrs.buildInputs ++ [ super.nss ];
            });
          };
        };

        # ====================================================================
        # NIXOS MODULES - REUSABLE CONFIGURATION MODULES
        # ====================================================================
        nixosModules = {
          # Basic Nix configuration applied to all systems
          basic = {
            nixpkgs = {
              config = nix-config;
              overlays = [ inputs.self.overlays.packages inputs.self.overlays.overrides ];
            };
            nix = {
              inherit (nix-config) extraOptions;
              registry = {
                stable = { from = { id = "stable"; type = "indirect"; }; flake = inputs.nixpkgs; };
                unstable = { from = { id = "unstable"; type = "indirect"; }; flake = inputs.nixpkgs-u; };
              };
            };
          };

          # Common modules applied to most systems
          commonModules = {
            imports = [
              # Nix configuration
              self.nixosModules.basic

              # Nix rice (theming configuration)
              inputs.nix-rice.modules.default
              ./nixos/rice.nix

              # Secret management with ragenix
              inputs.ragenix.nixosModules.default
              # inputs.agenix.nixosModules.default  # Alternative (commented out)

              # User configurations
              # { services.userborn.enable = true; }  # User creation service (commented out)
              self.nixosModules.bertof

              # Basic system defaults
              ./nixos/basics
            ];
          };

          # Home Manager configuration module
          homeManagerModules = { config, ... }: {
            home-manager = {
              useGlobalPkgs = true; # Use system packages globally
              useUserPackages = true; # Install packages to user profile
              extraSpecialArgs = {
                stable = import inputs.nixpkgs-s { inherit (config.nixpkgs) system; }; # Pass stable channel to home-manager
                unstable = import inputs.nixpkgs-u { inherit (config.nixpkgs) system; }; # Pass unstable channel to home-manager
              };
            };
          };

          # Main modules for desktop setups
          mainModules = {
            imports = [
              inputs.nix-index-database.nixosModules.nix-index # Package index database
              ./nixos/pro_audio.nix # Professional audio configuration
              ./nixos/kdeconnect.nix # KDE connectivity
              ./nixos/opentabletdriver.nix # Tablet driver

              self.nixosModules.bertof-rclone # Rclone cloud storage for bertof

              ./nixos/hyprland.nix # Hyprland window manager
            ];
            home-manager.users.bertof.imports = [ ./hm/hyprland.nix ]; # User-specific Hyprland config
            services.earlyoom.enable = true; # Out of memory killer
          };

          # Installer modules for system bootstrapping
          installerModules = {
            imports = [
              self.nixosModules.commonModules
              # Home manager for installer
              inputs.home-manager-u.nixosModules.default
              self.nixosModules.homeManagerModules
              ./nixos/installer.nix # Installer-specific configuration
            ];
          };

          # User configuration: bertof
          bertof = { imports = [ ./nixos/users/bertof.nix ]; };

          # bertof with rclone cloud storage
          bertof-rclone = {
            imports = [ self.nixosModules.bertof ];
            age.secrets.rclone_bertof = { file = ./secrets/rclone_bertof.age; owner = "bertof"; };
            home-manager.users.bertof.imports = [ ./hm/rclone-mount-bertof.nix ];
          };

          # User configuration: tiziano
          tiziano = { imports = [ ./nixos/users/tiziano.nix ]; };

          # tiziano with rclone cloud storage
          tiziano-rclone = {
            imports = [ self.nixosModules.tiziano ];
            age.secrets.rclone_tiziano = { file = ./secrets/rclone_tiziano.age; owner = "tiziano"; };
            home-manager.users.tiziano.imports = [ ./hm/rclone-mount-tiziano.nix ];
          };
        };

        # ====================================================================
        # NIXOS CONFIGURATIONS - SYSTEM DEFINITIONS
        # ====================================================================
        nixosConfigurations = {
          # ==================================================================
          # THOR - AMD Desktop System
          # ==================================================================
          thor = inputs.nixpkgs-s.lib.nixosSystem rec {
            system = "x86_64-linux";
            specialArgs = {
              stable = inputs.nixpkgs-s.legacyPackages.${system}; # Pass stable channel
              unstable = inputs.nixpkgs-u.legacyPackages.${system}; # Pass unstable channel
            };
            modules = [
              # Hardware-specific configurations
              inputs.nixos-hardware.nixosModules.common-cpu-amd
              inputs.nixos-hardware.nixosModules.common-pc-ssd

              # Home manager
              inputs.home-manager-s.nixosModules.default
              self.nixosModules.homeManagerModules

              # Base and main modules
              self.nixosModules.commonModules
              self.nixosModules.mainModules

              # Hardware and system-specific configuration
              ./instances/thor/hardware-configuration.nix
              ./instances/thor/configuration.nix

              # Additional services
              ./nixos/virtualization.nix
              ./nixos/steam.nix # Steam gaming platform
              ./nixos/ollama.nix # AI/LLM service
              # ./nixos/ollama-ui.nix # Web UI for Ollama
              ./nixos/garage.nix # Object storage service

              # User-specific home manager configuration
              {
                home-manager.users.bertof.imports = [
                  inputs.nix-index-database.homeModules.nix-index
                  ./instances/thor/hm.nix
                ];
              }
            ];
          };

          # ==================================================================
          # SIF - Intel Desktop System
          # ==================================================================
          sif = inputs.nixpkgs-s.lib.nixosSystem rec {
            system = "x86_64-linux";
            specialArgs = {
              stable = inputs.nixpkgs-s.legacyPackages.${system}; # Pass stable channel
              unstable = inputs.nixpkgs-u.legacyPackages.${system}; # Pass unstable channel
            };
            modules = [
              # Intel-specific hardware configurations
              inputs.nixos-hardware.nixosModules.common-cpu-intel-cpu-only
              inputs.nixos-hardware.nixosModules.common-gpu-intel-comet-lake
              inputs.nixos-hardware.nixosModules.common-pc-ssd

              # Home manager
              inputs.home-manager-s.nixosModules.default
              self.nixosModules.homeManagerModules

              # Base and main modules
              self.nixosModules.commonModules
              self.nixosModules.mainModules

              # Hardware and system-specific configuration
              ./instances/sif/hardware-configuration.nix
              ./instances/sif/configuration.nix

              # Additional services
              ./nixos/virtualization.nix
              ./nixos/steam.nix # Steam gaming platform
              ./nixos/ollama.nix # AI/LLM service
              # ./nixos/ollama-ui.nix # Web UI for Ollama
              ./nixos/garage.nix # Object storage service

              # User-specific home manager configuration
              {
                home-manager.users.bertof.imports = [
                  inputs.nix-index-database.homeModules.nix-index
                  ./instances/sif/hm.nix
                ];
              }
            ];
          };

          # ==================================================================
          # ODIN - Intel Laptop/Server Hybrid
          # ==================================================================
          odin = inputs.nixpkgs-s.lib.nixosSystem rec {
            system = "x86_64-linux";
            specialArgs = {
              stable = inputs.nixpkgs-s.legacyPackages.${system}; # Pass stable channel
              unstable = inputs.nixpkgs-u.legacyPackages.${system}; # Pass unstable channel
            };
            modules = [
              # Intel laptop hardware configurations
              inputs.nixos-hardware.nixosModules.common-cpu-intel
              inputs.nixos-hardware.nixosModules.common-pc-laptop
              inputs.nixos-hardware.nixosModules.common-pc-laptop-ssd

              # Home manager
              inputs.home-manager-s.nixosModules.default
              self.nixosModules.homeManagerModules

              # Base modules (server-focused)
              self.nixosModules.commonModules
              ./nixos/server # Server configurations

              # Hardware and system-specific configuration
              ./instances/odin/hardware-configuration.nix
              ./instances/odin/configuration.nix

              # Network and service configuration
              ./nixos/ip_forwarding.nix # IP forwarding for routing
              ./nixos/steam.nix # Steam gaming
              ./nixos/garage.nix # Object storage

              # Cloud storage for both users
              self.nixosModules.bertof-rclone
              self.nixosModules.tiziano-rclone
              {
                home-manager.users.bertof = import ./instances/odin/hm.nix;
                home-manager.users.tiziano = import ./instances/odin/hm_tiziano.nix;
              }
            ];
          };

          # ==================================================================
          # HEIMDALL - AMD Server
          # ==================================================================
          heimdall = inputs.nixpkgs-s.lib.nixosSystem rec {
            system = "x86_64-linux";
            specialArgs = {
              stable = inputs.nixpkgs-s.legacyPackages.${system}; # Pass stable channel
              unstable = inputs.nixpkgs-u.legacyPackages.${system}; # Pass unstable channel
            };
            modules = [
              # AMD server hardware configurations
              inputs.nixos-hardware.nixosModules.common-cpu-amd
              inputs.nixos-hardware.nixosModules.common-gpu-amd
              inputs.nixos-hardware.nixosModules.common-pc-ssd

              # Home manager
              inputs.home-manager-s.nixosModules.default
              self.nixosModules.homeManagerModules

              # Base modules (server-focused)
              self.nixosModules.commonModules
              ./nixos/server # Server configurations

              # Hardware and system-specific configuration
              ./instances/heimdall/hardware-configuration.nix
              ./instances/heimdall/configuration.nix

              # Network and service configuration
              ./nixos/ip_forwarding.nix # IP forwarding for routing
              ./nixos/torrentbox.nix # Torrent/download service
              ./nixos/nextcloud.nix # Cloud storage/file sync
              ./nixos/immich.nix # Photo management service
              ./nixos/forgejo.nix # Git hosting (Forgejo/Gitea fork)
              ./nixos/garage.nix # Object storage service
              ./nixos/ollama.nix # AI/LLM service

              # Cloud storage and secrets
              self.nixosModules.bertof-rclone
              self.nixosModules.tiziano
              {
                home-manager.users.bertof = import ./instances/heimdall/hm.nix;
                # GitLab Runner secrets for CI/CD
                age.secrets = {
                  heimdall-gitlab-runner-nix.file = ./secrets/heimdall-gitlab-runner-nix.age;
                  heimdall-gitlab-runner-docker-images.file = ./secrets/heimdall-gitlab-runner-docker-images.age;
                  heimdall-gitlab-runner-default.file = ./secrets/heimdall-gitlab-runner-default.age;
                };
              }
            ];
          };

          # ==================================================================
          # FREYA - ARM64 System (Commented out)
          # Raspberry Pi 4-based system (currently not used)
          # ==================================================================
          # freya = inputs.nixpkgs.lib.nixosSystem {
          #   system = "aarch64-linux";
          #   modules = [
          #     inputs.nixos-hardware.nixosModules.raspberry-pi-4
          #     ({ lib, ... }: { boot.supportedFilesystems = lib.mkForce [ "btrfs" "reiserfs" "vfat" "f2fs" "xfs" "ntfs" "cifs" ]; })
          #     self.nixosModules.server
          #     ./instances/freya/hardware-configuration.nix
          #     ./instances/freya/configuration.nix

          #     ./nixos/torrentbox.nix
          #     ./nixos/minio_server.nix
          #     # ./nixos/ntfy.nix

          #     self.nixosModules.tiziano
          #     { home-manager.users.bertof = import ./instances/freya/hm.nix; }
          #   ];
          # };

          # ==================================================================
          # BALDUR - Intel Server
          # ==================================================================
          baldur = inputs.nixpkgs-s.lib.nixosSystem rec {
            system = "x86_64-linux";
            specialArgs = {
              stable = inputs.nixpkgs-s.legacyPackages.${system}; # Pass stable channel
              unstable = inputs.nixpkgs-u.legacyPackages.${system}; # Pass unstable channel
            };
            modules = [
              # Intel server hardware configurations
              inputs.nixos-hardware.nixosModules.common-cpu-intel
              inputs.nixos-hardware.nixosModules.common-pc-ssd

              # Home manager
              inputs.home-manager-s.nixosModules.default
              self.nixosModules.homeManagerModules

              # Base modules (server-focused)
              self.nixosModules.commonModules
              ./nixos/server # Server configurations

              # Hardware and system-specific configuration
              ./instances/baldur/hardware-configuration.nix
              ./instances/baldur/configuration.nix

              # Network and service configuration
              ./nixos/ip_forwarding.nix # IP forwarding for routing
              ./nixos/garage.nix # Object storage service
              ./nixos/vaultwarden.nix # Password manager (Bitwarden compatible)
              ./nixos/uptime-kuma.nix # Uptime monitoring

              # User configurations
              self.nixosModules.bertof
              self.nixosModules.tiziano
              {
                home-manager.users.bertof = import ./instances/baldur/hm.nix;
                home-manager.users.tiziano = import ./instances/baldur/hm_tiziano.nix;
              }
            ];
          };

          # ==================================================================
          # LOKI - Intel System (Commented out)
          # Additional system currently not configured
          # ==================================================================
          # loki = inputs.nixpkgs.lib.nixosSystem {
          #   system = "x86_64-linux";
          #   modules = [
          #     inputs.nixos-hardware.nixosModules.common-cpu-intel
          #     inputs.nixos-hardware.nixosModules.common-pc-ssd
          # self.nixosModules.commonModules
          #     self.nixosModules.server
          #     ./instances/loki/hardware-configuration.nix
          #     ./instances/loki/configuration.nix

          #     self.nixosModules.tiziano
          #     {
          #       home-manager.users.bertof = import ./instances/odin/hm.nix;
          #       home-manager.users.tiziano = import ./instances/odin/hm_tiziano.nix;
          #     }
          #   ];
          # };
        };

      };
    };
}