nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-05-20 10:34:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Wrote Plinth's design document.

Browse Source 
This specs out the system and covers control flow through a user's interaction.
This commit is contained in:
Nick Daly 2014-05-31 14:55:24 -05:00
parent 9cf6ca9f47
commit a45aad5ed7
1 changed files with 50 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
doc/design.mdwn Normal file
View File

@ -0,0 +1,50 @@
<!-- -*- mode: markdown; mode: refill; fill-column: 80 -*- -->
# Plinth's Design
Struturally, 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. Theo
nly 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 `plint/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.