{
  description = "mat's nix configs";

  inputs = {
    # Package sets
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    nixpkgs-stable.url = "github:NixOS/nixpkgs/nixpkgs-22.11-darwin";
    nixpkgs-master.url = "github:NixOS/nixpkgs/master";

    # Flake helpers
    flake-utils.url = "github:numtide/flake-utils";

    # Environment/system management
    darwin.url = "github:lnl7/nix-darwin/master";
    darwin.inputs.nixpkgs.follows = "nixpkgs";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    home-manager.inputs.utils.follows = "flake-utils";

    # Config "flag" for disabling homebrew
    homebrew-enabled.url = "github:boolean-option/true";

    # pre-commit and hooks
    pre-commit.url = "github:cachix/pre-commit-hooks.nix";
    pre-commit.inputs.nixpkgs.follows = "nixpkgs";
    pre-commit.inputs.nixpkgs-stable.follows = "nixpkgs-stable";
    pre-commit.inputs.flake-utils.follows = "flake-utils";

    # Extra sources
    helix.url = "github:helix-editor/helix";
    helix.inputs.nixpkgs.follows = "nixpkgs";
    dark-mode-notify-src.url = "github:bouk/dark-mode-notify";
    dark-mode-notify-src.flake = false;
    ia-writer-family-src.url = "github:iaolo/iA-Fonts";
    ia-writer-family-src.flake = false;
    kitty-icon.url = "github:DinkDonk/kitty-icon";
    kitty-icon.flake = false;
    kitty-themes.url = "github:kovidgoyal/kitty-themes";
    kitty-themes.flake = false;
    fisher-src.url = "github:jorgebucaran/fisher";
    fisher-src.flake = false;
  };

  outputs =
    { self
    , flake-utils
    , pre-commit
    , ...
    }@inputs:
    let
      # this is a "functor" that takes an option name
      # this allows for creating identical modules
      # which can be accessed by appropriate paths darwin or home-manager
      mkPrimaryUserModule = import ./modules/mk-primary-user-module.nix;

      inherit (inputs.darwin.lib) darwinSystem;
      inherit (inputs.nixpkgs.lib)
        attrValues
        makeOverridable
        optionalAttrs;

      # Configuration for `nixpkgs`
      nixpkgsConfig = {
        config = { allowUnfree = true; };
        overlays = attrValues self.overlays;
      };

      homeStateVersion = "22.05";

      primaryUserInfo = {
        username = "mat";
        fullName = "mat ess";
        email = "mat@mat.services";
      };

      workUserInfo = {
        username = "mess";
        fullName = "Matthew Ess";
        email = "mess@yelp.com";
      };

      # helper for defining nix-darwin systems
      mkDarwinSystem =
        { modules ? [ ]
        , homeModules ? [ ]
        , ...
        }@args: import ./lib/mkDarwinSystem.nix self inputs nixpkgsConfig (args // {
          inherit homeStateVersion;
          modules = attrValues self.darwinModules ++ modules;
          homeModules = attrValues self.homeManagerModules ++ homeModules;
        });
    in
    {
      # `nix-darwin` configs
      darwinConfigurations =
        let
          bootstrap-x86 = makeOverridable darwinSystem {
            system = "x86_64-darwin";
            modules = [ ./darwin/bootstrap.nix { nixpkgs = nixpkgsConfig; } ];
          };
        in
        {
          # Mininal configurations to bootstrap systems
          inherit bootstrap-x86;
          bootstrap-arm = bootstrap-x86.override { system = "aarch64-darwin"; };

          # M1 MBP
          matbook = mkDarwinSystem {
            primaryUser = primaryUserInfo;
            modules = [
              ({ pkgs, ... }: {
                networking.computerName = "matbook pro m1";
                networking.hostName = "matbook";
                networking.knownNetworkServices = [
                  "Wi-Fi"
                ];
                nix.settings.cores = 2;
                nix.settings.max-jobs = 4;

                homebrew.casks = [
                  # games
                  "gog-galaxy"
                  "origin"
                  "sony-ps-remote-play"
                  "steam"
                ];
                home-manager.sharedModules = [{
                  programs.fish.shellAliases = {
                    code = "${pkgs.vscodium}/bin/codium";
                  };
                  programs.ssh.matchBlocks.remarkable = {
                    hostname = "10.11.99.1";
                    user = "root";
                    port = 22;
                  };
                  programs.vscode.package = pkgs.vscodium;
                }];
              })
            ];
          };

          yelpbook-m1 = mkDarwinSystem {
            primaryUser = workUserInfo;
            modules = [
              ({ pkgs, lib, ... }: {
                users.primaryUser = workUserInfo;
                networking.knownNetworkServices = [
                  "Wi-Fi"
                ];
                nix.settings.cores = 2;
                nix.settings.max-jobs = 5;

                homebrew.casks = [ "itsycal" ];
                home-manager.sharedModules = [{
                  # TODO: how to remove this entirely?
                  home.file.".tarsnaprc" = lib.mkForce { text = ""; };
                  home.packages = [ pkgs.yubiswitch ];
                  programs.ssh.matchBlocks.devbox = {
                    hostname = "csdev4";
                    forwardAgent = true;
                    serverAliveInterval = 120;
                  };
                  programs.fish.functions.devbox.body = ''
                    ssh -t devbox "agenttmux attach; or agenttmux new -s yelp"
                  '';
                  launchd.agents.tarsnap.enable = lib.mkForce false;
                }];
              })
            ];
          };
        };

      # Overlays --------------------------------------------------------------- {{{

      overlays = {
        # nixpkgs overlays
        pkgs-stable = _: prev: {
          pkgs-stable = import inputs.nixpkgs-stable {
            inherit (prev.stdenv) system;
            inherit (nixpkgsConfig) config;
          };
        };

        pkgs-unstable = _: prev: {
          pkgs-unstable = import inputs.nixpkgs {
            inherit (prev.stdenv) system;
            inherit (nixpkgsConfig) config;
          };
        };

        pkgs-master = _: prev: {
          pkgs-master = import inputs.nixpkgs-master {
            inherit (prev.stdenv) system;
            inherit (nixpkgsConfig) config;
          };
        };

        colors = import ./overlays/colors.nix;

        # Overlay useful on Macs with Apple Silicon
        apple-silicon = _: prev: optionalAttrs (prev.stdenv.system == "aarch64-darwin") {
          # Add access to x86 packages system is running Apple Silicon
          pkgs-x86 = import inputs.nixpkgs {
            system = "x86_64-darwin";
            inherit (nixpkgsConfig) config;
          };
        };

        homebrew-enabled = _: prev: optionalAttrs prev.stdenv.isDarwin {
          lib = prev.lib // { homebrew-enabled = inputs.homebrew-enabled.value; };
        };

        extra-pkgs = import ./pkgs { inherit inputs; };
      };

      # `nix-darwin` configs and modules
      darwinModules = {
        # configs
        bootstrap = import ./darwin/bootstrap.nix;
        defaults = import ./darwin/defaults.nix;
        general = import ./darwin/general.nix;
        homebrew = import ./darwin/homebrew.nix;
        # modules
        darwin-primary-user = mkPrimaryUserModule "users";
      };

      # home manager configurations
      homeManagerModules = {
        # services
        dark-mode-notify-service = import ./home/services/dark-mode-notify.nix;
        tarsnap-service = import ./home/services/tarsnap.nix;
        # etc
        files = import ./home/files.nix;
        fish = import ./home/fish.nix;
        git = import ./home/git.nix;
        helix = import ./home/helix.nix;
        kitty = import ./home/kitty.nix;
        programs = import ./home/programs.nix;
        starship = import ./home/starship.nix;
        starship-symbols = import ./home/starship-symbols.nix;
        # modules
        programs-kakoune-extras = import ./modules/home/programs/kakoune/extras.nix; # currently unused
        programs-helix-extras = import ./modules/home/programs/helix/extras.nix;
        programs-kitty-extras = import ./modules/home/programs/kitty/extras.nix;
        home-primary-user = mkPrimaryUserModule "home";
      };

      templates = import ./templates;
    } // flake-utils.lib.eachDefaultSystem (system: {
      legacyPackages = import inputs.nixpkgs (nixpkgsConfig // { inherit system; });

      checks.pre-commit = pre-commit.lib.${system}.run {
        src = ./.;
        hooks = {
          deadnix.enable = true;
          nixpkgs-fmt.enable = true;
          statix.enable = true;
        };
      };

      devShells = let pkgs = self.legacyPackages.${system}; in {
        default = pkgs.mkShell {
          inherit (self.checks.${system}.pre-commit) shellHook;
        };
        # TODO: add utility devShells here
      };
    });
}