# Architecture

## Format

The configuration file (`install.cfg`) is split into two parts. The first part is the schema part describing the possible options the end user might choose.
The second part is the template part, holding a template that is rendered and then executed line by line.
This split was chosen to have easy access to the option variable name, pretty print name, description and type.


### Schema

The schema part can be encoded with JSON or YAML. The library first tries to load the schema part with a safe yaml loader and when that fails with a json loader.

JSON Schema is a structured and well defined format. We use it to define options and flags.  
Flags are properties of type `boolean` and with the default `false`. Currently the cli will error, when the default is not set.  
Options can also be of type `number` or `string`.  

To define choice options (`["windows", "linux"]`) enum type is used.  
Though JSON Schema misses in itself the funcionality to save `title` and `description` for the enum values. 
This results in the need to save said data separately from the JSON Schema.
Said data is stored in the root keys `pretty` and `description`, while the schema is stored in `schema`.

This makes it necessary to detect, if the JSON Schema is in the root of the JSON/YAML or in the key `schema`.

The schema is validated and the end user input is checked before rendering the template. 


### Jinja Template

The template is given the parsed variables defined by the JSON Schema. This results in the variables having some type safety.

To support some common functionality, two macros are injected into the template before it is rendered (`raise` and `command`).
The template is rendered by a sandboxed renderer, as rendering a jinja template implies executing untrusted code.


### Composite Format

Havind a composite format configuration file has some adavantages and some disadvantages.

#### Advantages:
* One file holds the configuration.
* Structured and unstructured data can be held.
* Easy sharing.

#### Disadvantages:
* Missing IDE support.

The missing IDE support can be bypassed by developing the configuration in different files (`.yml` and `.json`).
The composite format could be build in the future by the cli from those separate files.


## CLI

Options for configurations are generated on the fly.
Click `MultiCommand` is used for loading the configuration file and parsing the schema for options.