Project Structure

This chapter sums the directory structure, configuration and . For a high-level overview, see Overview of the Components and Packages.

Directory Structure

Project is divided into several folders:

  • config/: Directory for environment-specific configuration.

  • dev_scripts/: Useful scripts for development.

  • docker/: Support files and configuration that is required to run the application in Docker containers.

  • docs/: Sources for this documentation.

    • build/: Directory containing compiled documentation.

  • ppc_robot/: Python package with general configuration.

    • manage.py: Django Admin CLI. Might be also run using the ppc_robot command after the package has been successfully installed.

    • settings.py: General application configuration.

    • urls.py: Configuration of Django URL Dispatcher.

  • ppc_robot_cluster/: Utilities for generating Kubernetes manifests a scaling the cluster.

  • ppc_robot_lib/: Main library containing data model, connectors for all external services and steps used to execute reports. This package is used by all components of PPC Robot.

  • ppc_robot_task_types/: Definition of task types that are available to users.

  • ppc_robot_tests/: Package with all tests of PPC Robot. The root directory contains generic configuration and fixtures, the sub-directories contains tests:
    • unit/: Unit tests of PPC Robot’s classes.

      • ppc_robot_lib/

      • ppc_robot_web/

      • ppc_robot_worker/

    • integration/: Integration tests of PPC Robot’s backend.

      • ppc_robot_task_types/

    • frontend/: Integration tests of PPC Robot’s frontend and web-backend.

  • ppc_robot_web/: Package with web application interface and web-backend. Based on standard Django structure. Main sub-folders:
    • assets/: CSS and JS files. Contains assets that needs to be compiled into a Single Page Application.

      • css/

      • js/

      • tests/

    • locale/: Translations.

    • management/commands/: Management commands, can be run using ppc_robot.

    • migrations/: Database migrations.

    • models/: Database models.

    • operations/: WebSocket operations.

    • serializers/: Serializers.

    • static/: Static files.

      • bundles/: Compiled JS and CSS bundles.

      • ppc_robot_web/: Images and other assets that can be used directly without compiling.

    • templates/: HTML templates.

    • views/: Views.

    • routing.py/: Message routing for Django Channels.

    • urls.py: URL routing definition.

  • ppc_robot_worker/: Package with PPC Robot backend worker.

Configuration

The main application configuration resides in ppc_robot/settings.py. It contains configuration of the application structure and provides defaults suitable for running in production. However, it does not contain environment-specific configuration such as database server credentials, secret keys, Sentry configuration etc.

In order to run the application, you have to create your own configuration with these settings. The file should be named be placed in the config directory. Sample is provided in config/local_settings.py.sample. Please note that you can include multiple files in the directory, but they will be loaded in the order they are returned by glob.glob(). This is not alphabetical order! Configuration files therefore cannot rely on order they are loaded.

Docker Containers

There are several Dockerfiles in the root directory of the project:

  • Dockerfile.base: base container with preinstalled system dependencies, directory structure and system configuration.

  • Dockerfile.lib: base container with installed PPC Robot package. Contains all required project files and executables.

  • Dockerfile.scheduler: container that runs the scheduler (Celery beats).

  • Dockerfile.task_worker: container that runs backend worker. Tasks from a specified queue can be consumed by using the PPC_ROBOT_TASK_WORKER_QUEUE env variable.

  • Dockerfile.web: container that runs the web interface. Contains compiled JS and CSS assets, translation files etc.,all prepared to be used by the web application.

To build all these containers, use make:

make docker_images