# Design

> The design philosophies underpinning the work here.

---

LLMS index: [llms.txt](/llms.txt)

---

## Design Philosophy

### Freedom of Information

No person stands alone in creating anything. Every part of what you make is
built off of the labor of others and to claim that you stand out alone with
inventions that you alone built is arrogant. Every bit of work that you have
done was enabled by tools created by others. Every bit of knowledge that you use
to create something is a refinement on knowledge discovered by others. You are
not special and neither am I. Our greatest strength is our capacity to uplift
each other and help out the person who comes next with the understanding and
expectation that they will do the same for you.

As a part of that philosophy this repository serves as a publicly usable example
of the works and knowledge that have gone into creating the fixed points
defining these configurations. They are free to use and extend on as long as the
social contract of educate and give as freely as you are able to is upheld.

### Version as configuration not as integration

Traditionally systems are configured via a set of actions performed one after
another in a live environment. This makes every single step have the possibility
of being affected by the steps that came before it and affecting the steps that
are to come after it. This creates a problem when trying to recreate a system or
provide aid to others to derive their own system based on an existing one.

To combat this problem we use tools like nix to define a complete system
configuration that can be used to fully derive a system configuration that can
then be applied to a system's state. This system configuration can then be
tracked using version control to share and accept contributions allowing other
users to create a similar system with their own state specific to their
use-case.

### Composability

Things are split into modules so that they can be opted into one at a time. This
also helps with separation of concerns as a side effect.

### Separation of concerns

> [!TODO]
>
> - explain what a dendrite is
> - describe how we use import tree with dendrites.

<style>
.path-tree-wrap {
  overflow-x: auto;
}
.path-tree {
  border-collapse: collapse;
}
.path-tree th,
.path-tree td {
  padding: 0.25rem 0.75rem;
  white-space: nowrap;
  border-bottom: 1px solid var(--bs-border-color, #dee2e6);
}
.path-tree th:first-child,
.path-tree td:first-child {
  position: sticky;
  left: 0;
  background: var(--bs-body-bg, #fff);
}
</style>

<div class="path-tree-wrap">
  <table class="path-tree">
    <thead>
      <tr>
        <th>Path</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/const"><code>/const</code></a></td>
        <td>shared constants used by many parts of the configuration</td>
      </tr>
      <tr>
        <td><a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/lib"><code>/lib</code></a></td>
        <td>shared library code used by many parts of the configuration</td>
      </tr>
      <tr>
        <td><a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules"><code>/modules</code></a></td>
        <td>modules that define a system</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/options"><code>options</code></a></td>
        <td>values that are to be used by command line tools</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/fleet"><code>fleet</code></a></td>
        <td>fleet configuration options</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/nixos"><code>nixos</code></a></td>
        <td>NixOS configuration options</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/nixos/fleet-adaptors"><code>fleet-adaptors</code></a></td>
        <td>tools for passing configuration from a fleet to a nixos device</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/nixos/home-manager-adaptors"><code>home-manager-adaptors</code></a></td>
        <td>tools for passing configuration from a home configuration to a nixos device</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/nixos/pkgs"><code>pkgs/&lt;package&gt;</code></a></td>
        <td>instructions configuring arbitrary program packages</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;└── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/nixos/programs"><code>programs/&lt;program&gt;</code></a></td>
        <td>a program configured to run on a NixOS system along with any extension module to it</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/darwin"><code>darwin</code></a></td>
        <td>mac system configuration options</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/home-manager"><code>home-manager</code></a></td>
        <td>home manager configuration options</td>
      </tr>
      <tr>
        <td>├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/hosts"><code>hosts</code></a></td>
        <td>implementation of system configurations</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/hosts/darwin"><code>darwin</code></a></td>
        <td>implementations of mac system configurations</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/hosts/fleet"><code>fleet</code></a></td>
        <td>implementations of fleet configurations</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;├── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/hosts/nixos"><code>nixos</code></a></td>
        <td>implementations of NixOS configurations</td>
      </tr>
      <tr>
        <td>│&nbsp;&nbsp;└── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/hosts/home"><code>home-manager</code></a></td>
        <td>implementations of home configurations</td>
      </tr>
      <tr>
        <td>└── <a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/modules/syncthing"><code>syncthing</code></a></td>
        <td>legacy configuration method for syncthing between devices. (Should be moved to be a part of fleet configuration!)</td>
      </tr>
      <tr>
        <td><a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/tests"><code>/tests</code></a></td>
        <td>tests to run when validating changes do not cause regressions</td>
      </tr>
      <tr>
        <td><a href="https://git.jan-leila.com/jan-leila/nix-config/src/branch/main/npins"><code>/npins</code></a></td>
        <td>dependency management managed via npins</td>
      </tr>
      <tr>
        <td><code>/*/__tests__/</code></td>
        <td>Tests that are colocated with a module</td>
      </tr>
    </tbody>
  </table>
</div>

### Automation

> [!TODO]
>
> fill out section here

- well defined, well built specific tools are better than fragile general ones
- repeated tasks should have tools made to reduce the load on maintainers