---
feature_story: FS_29_54_67_86
feature_title: project `dir_structure`
feature_status: TEST
---

# Purpose

This features describes the directory structure (a convention):
*   which `argrelay` uses for itself
*   which should be used for integration projects based on `argrelay` (to make scripts re-use-able)

# Relative paths

To make it unambiguous that path is relative to project root dir,
it is referred to as `argrelay_dir` in scripts and indicated as `@/` in docs and comments,
for example: `@/exe/bootstrap_env.bash`.

Every script knows its relative position to `argrelay_dir` (or `@/`) to locate it.

Note that project root may or may not match repo root (e.g. Git):
*   it does for `argrelay` itself
*   but it may not for `argrelay`-based projects

# Top directories

See also `TopDir` enum.

```
@                 # project root
│
...
├── docs          # Documentation, notes, etc.
├── src           # Prod code
├── tests         # Test code
...
├── conf          # Git-ignored dir for all configuration files specific to the target environment.
│                 # Normally, `@/conf/` dir is a symlink to one of the sub-dirs under `@/dst/`,
│                 # if target environment configurations is decided to be stored in the same repo.
├── dst           # Target environment configurations (dst = "destination") - see also `@/conf/` dir.
│
├── data          # Files with various static data in different formats.
...
├── exe           # Executable artifacts which should NOT be accessible via `PATH`.
├── bin           # Executable artifacts which should be accessible via `PATH`.
...
├── var           # State files (e.g. PID files for running server, generated data, lock files, etc.).
...
├── tmp           # Git-ignored dir for disposable files (e.g. downloads).
├── drafts        # Git-ignored dir to stash files without committing them (yet).
├── dist          # Git-ignored dir for files generated by Python tools.
├── build         # Git-ignored dir for files generated by Python tools.
...
```

# Individual dir and file paths

## `@/exe/`

Dir `@/exe/` contains immediately executable files.

## `@/conf/`

Dir `@/conf/` contains configuration files specific to target installation environment.

Normally, it is a symlink.

The symlink itself is not supposed to be version controlled by this repo, but the dir it points to can be:
*   one of `@/dst/*` dirs under the same repo
*   any other dir

In practice, to keep config under version control within the same repo, `@/conf/` can be a symlink which
points to different version controlled dir (see sub-dirs under `@/dst/`) depending on the target installation environment.

To avoid being detected as modified when target installation environment changes, this `@/conf/` symlink is not committed.

This path is the default (lowest priority) - see [`FS_16_07_78_84.conf_dir_priority.md`][FS_16_07_78_84.conf_dir_priority.md].

## `@/dst/`

This dir contains sub-dirs with config files for multiple target environments.

For example:
*   Dir `@/dst/` may contain sub-dirs: `@/dst/target_env_a` and `@/dst/target_env_b`.
*   When the project is installed to environment `target_env_a`, `@/conf/` should be a symlink to `@/dst/target_env_a`.
*   When the project is installed to environment `target_env_b`, `@/conf/` should be a symlink to `@/dst/target_env_b`.

## `@/conf/python_env.conf.bash`

This config script is used by `@/exe/bootstrap_env.bash` to `source`:
*   path to initial Python interpreter (to init `venv` with)
*   path to `venv` to activate

If `venv` is wrongly initialized:
*   update `@/conf/python_env.conf.bash`
*   delete old `venv`
*   initialize new `venv` by re-running `@/exe/bootstrap_env.bash`

## `@/conf/env_packages.txt`

It contains `pip freeze` output (AKA `requirements.txt`, just renamed) with Python packages and their versions.

Script `@/exe/bootstrap_env.bash` installs packages according to this file.

## `@/conf/argrelay_client.json`

Config for `argrelay` client.

Unlike `argrelay` server YAML config, config for `argrelay` client is JSON for performance reasons.

## `@/conf/argrelay_server.yaml`

Config for `argrelay` server.

## `@/conf/argrelay_plugin.yaml`

Config for `argrelay` plugin(s).

## `@/exe/bootstrap_env.bash`

It bootstraps environment according to configs in `@/conf/`.

See FS_85_33_46_53 `bootstrap_env`.

## `@/exe/check_env.bash`

It checks environment for any issues.

See FS_36_17_84_44 `check_env`.

## `@/exe/dev_shell.bash`

It starts fully configured shell according to configs in `@/conf/` to try `argrelay`-linked commands.

To avoid starting it, see `@/exe/shell_env.bash`.

See FS_58_61_77_69 `dev_shell`.

## `@/conf/dev_shell_env.bash`

It is a hook used to additionally configure `@/exe/dev_shell.bash`.

## `@/exe/run_argrelay_server`

It runs `argrelay` server (in foreground).

## `@/exe/run_argrelay_client`

It is **not** used directly - instead, Bash calls it on `Alt+Shift+Q`-query or `Tab`-completion.

## `@/exe/shell_env.bash`

It is what `~/.bashrc` has to `source` to avoid starting `@/exe/dev_shell.bash`.

## `@/conf/shell_env.conf.bash`

It lists `argrelay`-linked commands (to be stored in `@/bin` and exposed via `PATH`).

## `@/var/argrelay_client.server_index`

It contains index of one of the configured servers client used for the previous request.

See FS_93_18_57_91 client fail over to redundant servers.

[FS_16_07_78_84.conf_dir_priority.md]: FS_16_07_78_84.conf_dir_priority.md
