Skip to content

Latest commit

 

History

History
180 lines (125 loc) · 9.19 KB

architecture.md

File metadata and controls

180 lines (125 loc) · 9.19 KB
Raw

Architecture

This document describes the architecture of CLOMonitor, detailing each of the components, what they do and where they are located in the source repository.

Repository layout

The following directories present at the top level of the repository represent some of the key locations in the codebase:

clomonitor
├── .github
├── chart
├── clomonitor-apiserver
├── clomonitor-archiver
├── clomonitor-core
├── clomonitor-linter
├── clomonitor-registrar
├── clomonitor-tracker
├── database
├── docs
└── web

  • .github: contains the Github Actions workflows.

  • chart: contains the CLOMonitor Helm chart, which is the recommended installation method.

  • clomonitor-apiserver contains the source code of the apiserver backend component.

  • clomonitor-archiver contains the source code of the archiver backend component.

  • clomonitor-core: contains the source code of the core backend modules, like linter and score.

  • clomonitor-linter: contains the source code of linter CLI tool.

  • clomonitor-registrar: contains the source code of the registrar backend component.

  • clomonitor-tracker: contains the source code of the tracker backend component.

  • database: contains all code related to the database layer, such as the schema migrations, functions and tests.

  • docs: contains the project documentation.

  • web: contains the source code of the web application.

Layers

CLOMonitor is structured in multiple layers, each of them providing a set of services to adjacent layers.

  • Database: this layer provides data services, controlling the database schema and its migrations and providing a set of functions that will act as an API for outer layers, abstracting them in many cases from the internal database structure. CLOMonitor uses PostgreSQL as datastore. Please see the database section for more details.

  • Core library: this layer represents a set of Rust APIs that allow performing core operations supported by CLOMonitor, such as linting a repository or calculating scores. Please see the core library section for more details.

  • Backend applications: this layer represents the applications that form the backend: apiserver, registrar and tracker. These applications rely on the database and core library layers to perform their tasks. Please see the backend applications section for more details.

  • Linter CLI: this layer represents a CLI tool that allows projects to lint their repositories locally or from their CI workflows. Please see the linter CLI section for more details.

  • Web application: this layer represents the CLOMonitor's web user interface. It uses the HTTP API exposed from the apiserver to interact with the backend. Please see the web application section for more details.

Database

The database layer is defined by the database schema and a set of functions, which are handled using migrations. Migrations use Tern, and are automatically applied during the installation and upgrades by a Kubernetes job named dbmigrator. There are unit tests available for both the schema and the functions.

database
├── migrations
│   ├── functions
│   │   └── ...
│   └── schema
│       └── ...
└── tests
    ├── functions
    │   └── ...
    └── schema
        └── ...

Core library

This layer represents a set of Rust APIs that provide some core functionality to other layers, like the backend applications or the CLI tool.

It's composed of two modules:

  • linter: this module implements the core linting functionality of CLOMonitor. All checks currently run by CLOMonitor are handled by this module, and both the CLI tool and the tracker rely on it. The linter is able to run multiple check sets on each repository. Each check set defines a number of checks that will be run on the repository. For more details about what checks are run on each check set, please see the checks documentation.

  • score: this module is in charge of scoring reports produced by the linter. The linter will produce different reports for each of the kinds supported, and each of the reports will be scored differently as well. In addition to the reports' scoring functionality, this module provides some score related features as well, like rating a given score or merging multiple scores.

Backend applications

The backend applications are apiserver, archiver, registrar and tracker. They are located in the clomonitor-apiserver, clomonitor-archiver, clomonitor-registrar and clomonitor-tracker directories respectively. Each of the applications' directory contains a Dockerfile that will be used to build the corresponding Docker image.

.
├── clomonitor-apiserver
│   ├── Cargo.toml
│   ├── Dockerfile
│   ├── src
│   └── templates
├── clomonitor-archiver
│   ├── Cargo.toml
│   ├── Dockerfile
│   └── src
├── clomonitor-registrar
│   ├── Cargo.toml
│   ├── Dockerfile
│   └── src
└── clomonitor-tracker
    ├── Cargo.toml
    ├── Dockerfile
    └── src

  • apiserver: this component provides an HTTP API that exposes some endpoints used by the web application layer, plus some extra functionality like badges configuration, reports summary, etc. It is also in charge of serving the web application static assets.

  • archiver: this component is in charge of creating snapshots of projects' data periodically. It's launched periodically from a Kubernetes cronjob.

  • registrar: this component is in charge of registering the projects available on each foundation's data file in the database. It's launched periodically from a Kubernetes cronjob.

  • tracker: this component is in charge of linting and scoring all projects and repositories registered in the database. It's launched periodically from a Kubernetes cronjob.

Linter CLI

The linter CLI tool allows projects to lint their repositories locally or from their CI workflows. It generates a report by using the linter module available in the core library, it scores it and prints the results nicely.

$ export GITHUB_TOKEN=<your token>

$ clomonitor-linter --help
clomonitor-linter
Checks repository to verify it meets certain project health best practices

USAGE:
    clomonitor-linter [OPTIONS] --path <PATH> --url <URL>

OPTIONS:
        --check-set <CHECK_SET>      Sets of checks to run [default: code community] [possible
                                     values: code, code-lite, community, docs]
        --format <FORMAT>            Output format [default: table] [possible values: json, table]
    -h, --help                       Print help information
        --pass-score <PASS_SCORE>    Linter pass score [default: 75]
        --path <PATH>                Repository local path (used for checks that can be done
                                     locally)
        --url <URL>                  Repository url [https://github.com/org/repo] (used for some
                                     GitHub remote checks)
    -V, --version                    Print version information

Web application

The CLOMonitor's user interface is a single page application written in TypeScript using React. Its source code can be found in the web directory.

web
├── public
└── src
    ├── api
    ├── context
    ├── hooks
    ├── layout
    ├── styles
    └── utils

  • public: contains the base index.html file as well as some static assets, like images.

  • src/api: contains a wrapper to interact with the HTTP API exposed by the apiserver.

  • src/context: context used for the preferences across the entire app.

  • src/hooks: contains some custom React hooks.

  • src/layout: contains all React components. They are organized in different folders corresponding to the section of the UI they belong to.

  • src/styles: contains the stylesheets for the light and dark themes.

  • src/utils: contains some utilities used by the components.

Development environment setup

For more information about how to setup your development environment, please see this document.