Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• fioddor/FBonboarding

Hackathon: Easy the onboarding of new developers

Directories and files

• DEV: Development artifact. Not part of the product itself. No need to deploy this in execution environment.
• PRD: Part of the product, whether developed or integrated. Should be deployed in execution environment.

Directories

• folder name	type	short file description
  build	DEV?
  .ci	DEV	Continuous integration artifacts
  .container	DEV	Development container data.
  .git	DEV	{toolName:git , toolDesc: "A source-code version manager" }
  htmlcov	DEV	Testing coverage report.
  _ pycache _	DEV	Standard Python directory for cached compiled objects
  .pytest_cache	DEV	Pytest cache
  .vagrant	DEV	{toolName:Vagrant , toolDesc: "VM handler"}
  vagrant-scripts	DEV	{toolName:Vagrant , toolDesc: "VM handler"}

  folder name	type	short file description
  actions	PRD	Usually wrappers around each module. Run as external shell commands. See plinth/actions.py. No subdirectories.
  bin	PRD	Plinth OS launcher-script. Obvious filename and content. vs run?. No subdirectories.
  data	PRD	Static data used for deployment in OS. Subdirectory tree structure resembles destinations.
  debian	PRD	Packaging/publishing for Debian Archive. Allows standard deployment in Debian. Standard subdirectories.
  doc	PRD	FreedomBox docs. Don't touch here. Manual is pulled from the wiki.debian.org/*/FreedomBox/*. Please, edit there. On the other hand, the download and post-processing scripts live here.
  .eggs	PRD	Cache directory for plug-ins. See README.txt. Each plugin has its subdirectory. Egg-structure is standard.
  plinth	PRD	Freedombox WUI.
  Plinth.egg.info	PRD	Standard Python packaging/publishing info.
  preseed	PRD	Used for deployment in Debian. See https://wiki.debian.org/DebianInstaller/Preseed.
  static	PRD	Web's static parts (resources: themes, jslicense).

plinth/

• folder name	type	short file description
  locale	PRD	Literals translations
  migrations	PRD	Django-generated.
  modules	PRD	Each module has its own subdir here.
  _pycache_	PRD	Standard Python directory for cached compiled objects.
  templates	PRD	Django templates.
  templatetags	PED	Django...
  tests	DEV	Automatic testing (for development, not diagnostics).

Files should have minimal human-readable header-comments where possible

• file name	type	clear	short file description	tool (if is a DEV file)
  .coverage	DEV	data	Coverage data (automatically collected).	Coverage(?PyTest is a testing framework for Python).
  .coveragerc	DEV		Documented. See file content.	Coverage(?PyTest is a testing framework for Python).
  .gitignore	DEV		Tells git which files to ignore.	Git is a source-code version manager.
  .gitlab-ci.yml	DEV		Defines the contiuous integration (CI) circuit.	GitLab is a software development project manager.
  .style.yapf	DEV		Sets formatting parameters.	YAPF is a source code formatter.
  conftest.py	DEV		Pytest configuration for all tests.	?PyTest is a testing framework for Python.
  container	DEV		Script for handling the development container.	systemd-nspawn is a container handler.
  CONTRIBUTING.md	DEV		Documented. See file content.	-
  HACKING.md	DEV		Standard, obvious filename and content. Miss reference to CONTRIBUTING.md for more guidelines.	-
  manage.py	DEV		Documented. See file content.	?PyTest is a testing framework for Python.
  pytest.ini	DEV		Configuration for pyTest.	?PyTest is a testing framework for Python.
  setup.cfg	DEV		Sets testing parameters.	?PyTest is a testing framework for Python.
  Vagrantfile	DEV		Describes the development VM('s?) to Vagrant.	Vagrant is a VM handler.

  file name	type	clear	short file description	tool (if is a DEV file)
  COPYING.md	PRD		Standard doc, obvious filename and content.	-
  INSTALL.md	PRD		Standard doc, obvious filename and content.	-
  README.md	PRD		Standard doc, obvious filename and content.	-
  run	PRD		Plinth OS launcher-script. Obvious filename and content.	-
  setup.py	PRD		Documented. See file content	-

plinth/

• file name	type	clear	short file description	group
  actions.py	PRD		Actions. Explain actions concept and value.!	?
  action_utils.py	PRD		Python action utility functions. Elaborate!	FBX
  app.py	PRD		Base class for all FBX apps. Explain component concept.	FBX
  axes_app_config.py	PRD		Overriden ?AppConfig from django-axes to avoid monkey-patched ?LoginView. Elaborate!	django
  cfg.py	PRD		Configuration parser + defaults.	cfg
  clients.py	PRD		Utilities for providing clients info. Context!	WUI
  context_processors.py	PRD		Django context_processors. Intro	django
  daemon.py	PRD		Component for managing a background daemon or any systemd unit.. Context!	OS
  dbus.py	PRD		Expose some API over D-Bus. Intro	OS?
  develop.config	PRD		Configuration for develop mode. Intro	cfg
  errors.py	PRD		Project specific errors.	FBX
  forms.py	PRD		Common forms for use by modules.	?
  frontpage.py	PRD		Manage app shortcuts (cards) on front page. (The page via FBX icon at menu). Missing word in Shortcut description. ToDo XXX.	WUI
  glib.py	PRD		Module to handle glib main looop + asynchronous utilities. Context!	OS
  _ _ init _ _.py	PRD		Standard doc, obvious filename and content. Python init.py file for plinth module. When to update version.	-
  kvstore.py	PRD		Simple key/value store using Django models. (Cross-session persistency)	FBX
  log.py	PRD		Logger setup for FBX.	cfg, OS
  _ _ main _ _.py	PRD		Standard doc, obvious filename and content. Context!	FBX
  menu.py	PRD		Obvious filename and content. Context!	WUI
  middleware.py	PRD		Common django middleware. Elaborate!	django
  models.py	PRD		Django models for the main app. Elaborate! Django DB.	django
  module_loader.py	PRD		Discover, load and manage FBX aps. Intro	FBX
  network.py	PRD		Helper functions for working with network (manager).	OS
  notification.py	PRD		API to show notifications.	WUI
  package.py	PRD		Framework for installing + updating distro packages.	OS
  settings.py	?		Basic settings for Django. (for special cases)	django
  setup.py	PRD		Utilities for application setup. Context! CLI.	CLI
  signals.py	PRD		Django signals emitted within FBX.	django
  translation.py	PRD		Translation utilities.	django
  urls.py	PRD		Django URLconf file for all URLs.	django
  utils.py	PRD		Misc utils.	-
  views.py	PRD		Django main FBX views. Mention util functions!!	django
  web_framework.py	PRD		Setup Django web framework.	django
  web_server.py	PRD		Setup cherrypy webserver.	cherrypy

Architecture

FreedomBox is a Debian blend -> a Debian distribution -> a Linux/Unix OS.

FreedomBox Service (Plinth) is a WUI OS frontend to Debian

• implemented as a Django application deployed over Apache

• MVC -> templates, forms, views + some utilities in _init.py_ and plinth/ subdir.

• mostly Python (3), CSS uses Bootstrap. Minimal ?JavaScript usage.

The backend

• talks to systemd, network-manager, firewall, avahi, apt, etc...
• is implemented by actions. See actions.py for more info.