<!-- -*- mode: markdown; mode: refill; fill-column: 80 -*- -->

# Plinth's Design

Structurally, Plinth is very simple.  It's nothing more than a modular system to
hook a web UI to the command line and the underlying system.

Users enable modules which turn on features on the box and run actions.  The
only data Plinth itself should store are the modules users have and haven't
enabled.  The rest of the information that Plinth interacts with is read from
and written to the appropriate system configuration files.

The most important files in the Plinth project are the modules (in the
`plinth/modules` directory).  Those files create web pages that present
configuration options to the user and, when the user accepts the configuration,
runs the relevant action scripts.

In the simplest case, the user navigates to http://freedombox.lan/plinth/hello,
which runs the `plinth/modules/hello` file and displays the output as a web
page.  When the user hits "Submit" on the hello page's form, the hello module
runs the `plinth/actions/hello` script, which takes the user's input, escapes
it, removes any suspect input or dangerous options (by applying a **whitelist**
to the user's input) and then passing the remaining, safe, options to the
`/bin/hello` program.  The module chooses whether or not to display the output,
and the process is complete.

For example:

1. User requests http://freedombox.lan/plinth/hello

2. Plinth returns the response from `plinth/modules/hello`.

3. User submits Hello form.

4. Hello module runs `plinth/actions/hello`.

5. Hello action removes unsafe input.

6. Hello action runs hello system binary with only safe input.

7. Hello module may display output from hello binary.

8. The hello configuration process is complete.

In the above example, control flows in one of two ways:

1. `URL -> Module -> User`, where the user hasn't performed an action.

2. `URL -> Module -> Action -> Binary -> User`, where the user configures the
system.
