(the-structure-of-the-systems)=
# The Structure of the Systems

The systems in the System Template are stored in the `data` folder of the `system_template` Regolith filter. If your Regolith project uses the default configuration, it's located at `packs/data/system_template`. Each system has its own folder, and you can nest these folders as you like. The System Template filter recognizes any folder containing `_scope.json` and `_map.py` files as the root of a system.

Some directories may be used to group multiple systems together. These group directories are marked with the `_group_scope.json` file.

**Example Structure (important files are marked with ⭐):**
```
📁 system_template
  ⭐ scope.json
  ⭐ auto_map.json
  📁 [path/to/system]
    📝 example_python_file.py
    📝 example_json_file.json
    📝 example_file.example_extension
    ⭐ _scope.json
    ⭐ _map.py
  📁 [path/to/group/of/systems]
    ⭐ _group_scope.json
    📁 [path/to/system]
      ...
    📁 [path/to/system]
      ...
```

## auto_map.json

The auto map is used to map file extensions used in the systems to the output paths in Resource and Behavior Packs. Learn more about AUTO mapping in the {ref}`AUTO mapping<auto-mapping>` section. If you want to customize the auto mapping with the `auto_map.json` file, read the {ref}`Custom AUTO Mapping<custom-auto-mapping>` section.

## _map.py

The `_map.py` file is one of the most important files in every system.  Together with the `_scope.json` file, it is required for the directory to be considered a system. The `_map.py` file maps the files inside the system to their output paths, defines how conflicts should be handled (multiple files mapped to the same output path), and enables/disables some file generation features. Learn more about the `_map.py` file in  {ref}`The _map.py File<the-mappy-file>` section.

## _scope.json (system)

The `_scope.json` file of a system defines variables used in the `_map.py` file and other files generated by the System Template. It is required, along with the `_map.py` file, for the directory to be considered a system. Learn more about the `_scope.json` file in the {ref}`Scopes and Variables<scopes-and-variables>` section.

## scope.json (global)

The `scope.json` is the global scope file with variables accessible from all systems. It doesn't necessarily have to be in the root folder of the `system_template` filter. It's possible to configure the System Template to use a different file (see {ref}`Installation And Configuration<installation-and-configuration>` section). Learn more about scopes in the {ref}`Scopes and Variables<scopes-and-variables>` section.

## _group_scope.json

The group scope is a special scope file that defines variables for all systems inside a group. It also marks the root folder of the group. Learn more about scopes in the {ref}`Scopes and Variables<scopes-and-variables>` section.

## Other Files

Other files in the example structure would typically contain content similar to the files you would normally put in your Resource or Behavior Pack but organized differently. These files are the building blocks of the systems, and System Template exports them to the RP/BP folders according to the `_map.py` file.