# Architecture

## Introduction

This document provides an high-level overview of GGShield code base.

## Git repositories

- [py-gitguardian](https://github.com/GitGuardian/py-gitguardian): provides the Python package wrapping GitGuardian REST API. All API calls should be implemented in this package.
- [ggshield](https://github.com/GitGuardian/ggshield): uses py-gitguardian to implement the GitGuardian CLI.

## GGShield project tree

### `ggshield` directory

- ggshield
  - cmd: Implementation of the commands. Python modules in this package provide commands in the form of `<command_name>_cmd` functions. The file hierarchy in this package matches with ggshield commands. For example the implementation for `ggshield secret scan path` is in `cmd.secret.scan.path`.
  - verticals: Code specific to one vertical. This package contains one sub-package per vertical.
  - core: Basic modules used by the `verticals` and `cmd` modules.
  - utils: Generic code, not tied to ggshield. Could be easily reused in other projects.

#### Import rules

`cmd` modules are the top layer. They can import code from their matching module in the `verticals` package, from `core`, `utils` and `py-gitguardian`.

`verticals` modules can only import from `core`, `utils` and `py-gitguardian`.

`core` modules can only import from `utils` and `py-gitguardian`.

`utils` modules cannot import from any other ggshield modules. They also cannot import from `py-gitguardian` (to ensure the code in this package remains generic).

These import rules are enforced by [import-linter](https://pypi.org/project/import-linter/). The import-linter configuration is generated by the [generate-import-linter-config.py](../../scripts/generate-import-linter-config.py) script.

### `tests` directory

GGShield has two test suites: Unit tests exercise parts of the code. Functional tests exercise complete commands.

Both test suites can be run using `pytest`.

#### Unit tests

Unit tests must execute fast, so they do not access the network (mostly, see note below) and try to limit IO access. They can mock functions and uses [VCR.py](https://vcrpy.readthedocs.io/en/latest/index.html) to replay network communications.

Unit tests modules follow more-or-less closely the hierarchy of the `ggshield` directory.

About network access: network access is required to record VCR.py cassettes, but this only happens when writing new tests. The CI runs the unit test suite in a way which disables all network access.

#### Functional tests

Functional tests run the real `ggshield` commands without mocking anything. This means they access GitGuardian API for real, making them slow.

They are organized to match `ggshield` commands.
