docs: add hacking.md

LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Dustin Stiles
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

docs/internals/README.md

@@ -9,4 +9,5 @@ If you want to learn how DSFX works inside, here's what we got:
   all the code here!
 - [commit strategy](./commits.md) is the guide for writing commit messages that follow the Conventional Commits
   specification.
+- [hacking](./hacking.md) is the guide for developers who want to contribute to the project.
 - [handshake](./handshake.md) is the protocol for establishing a secure connection between two parties.

docs/internals/hacking.md

@@ -0,0 +1,111 @@
+# Hacking
+
+Welcome fellow hacker! This document is intended to help you get started with the codebase and
+understand how to use the various tools and libraries that are included. If you have any questions,
+please feel free to reach out to the maintainers.
+
+**Index**
+
+- [File Structure](#file-structure)
+
+---
+
+## File Structure
+
+There are three folders on the top level of the project. They are:
+
+- [cmd](#cmd)
+- [docs](#docs)
+- [internal](#internal)
+
+Files that are stored in the root of the project are generally used for configuration and
+documentation purposes, but we try to keep the number of files in the root of the project to a
+minimum.
+
+Currently we have the following files in the top level:
+
+- `.gitignore` - This file is used to tell git which files and directories to ignore when
+  committing changes to the repository.
+- `CHANGELOG.md` - This file is used to keep track of changes made to the codebase. It is
+  currently unused and reserved for future use.
+- `go.mod` - This file is used to manage the dependencies of the project. It is used by the Go
+  module system to track the dependencies of the project and ensure that the correct versions are
+  used. Our project does not have any external dependencies, so this file primarily serves to
+  establish the project as a Go module.
+- `README.md` - This file is used to provide information about the project. It is used to
+  document the project and provide instructions for how to use it. This file is intended to be
+  used as a reference for developers and users of the project.
+
+### cmd
+
+The `cmd` directory contains entry points for the various tools that are included in the project.
+Currently these are the `dsfx` and `dsfxctl` tools. They each define Go `main` packages that can
+be compiled and distributed.
+
+In general, code in this directory should be relevant to the starting, stopping, and running of the
+tools. It should not contain any business logic or other code that is not relevant to the tool
+itself. Rather, it should delegate to the code in the `internal` directory to do the actual work
+and serve as a thin bootstrapping layer.
+
+### docs
+
+The `docs` directory contains documentation for the project. Files that are children of this folder
+are intended to be viewed by end users. Feel free to peruse around and learn about the system.
+
+Files that are located in `docs/internals` are **not** intended for end users. They are intended for
+developers and contributors to the project. These files are intended to be used as a reference for
+understanding the codebase and how it works. The file you are reading right now is located in this
+folder.
+
+### internal
+
+The `internal` directory contains the core code of the project. This code is not intended for public
+use and is meant for internal use only. The code in this directory is organized into several
+subdirectories, each of which serves a specific purpose.
+
+#### internal/client
+
+This section contains the client code, which is what a user or admin runs on their local machine to
+interact with their server (see internal/peer). The client code is responsible for sending and
+receiving messages to and from the server, as well as handling user input and output. Currently the
+code for the CLI is located in this package, but we would love to see that moved to the `cmd`
+folder as it is not applicable to the library side of the tool. The direct consumer of this package
+is the `cmd/dsfxctl` main package.
+
+#### internal/lib
+
+This section contains shared libraries that are used by the rest of the codebase. They aren't
+intended for public use, but can be used freely throughout the rest of the application. Code that
+lives in this section should pay close attention to unit tests and benchmarking, as it is likely
+used in more than on place, which means that changes here are force multipliers for both bugs and
+performance.
+
+#### internal/peer
+
+This section contains the peer code, which is what the server runs on the remote machine. The peer
+code is responsible for communicating with the client code, other peers, and the filesystem. The
+direct consumer of this package is the `cmd/dsfx` main package.
+
+#### internal/sim
+
+This section of the codebase contains various helpers for simulating different parts of the system.
+You can use these helpers to simulate latency, corruption, and other external factors inside of
+your unit tests.
+
+Currently, these tools are most useful in tests as mock implementations of the system. They are not
+intended for production use. When we build out the simulation framework, these tools will mature
+and be targeted for that use case.
+
+#### internal/tool
+
+This section of the codebase contains various internal tools and scripts that are used for
+development, testing, and deployment purposes. These tools are not intended for public use and are
+meant for internal use only. Each one is a main package with an executable, usually with a single
+command. Some accept command line arguments, you will need to check the code for those.
+Alternatively, you may run the tool with `-h` to see the available options.
+
+The tools in this directory can be loosely compared to a `bin` directory, or maybe a `Makefile`.
+We prioritize using Go for our tools, so we try to stay inside of the Go ecosystem as much as
+possible. We also try to keep the tools as simple as possible, so that they are easy to use and
+understand. It is much better to have a lot of really small, really focused tools than a few
+massive tools that do everything.