# 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.