<a id="reference-charm-architecture"></a>

# Charm architecture

At its core, the WireGuard gateway charm is a highly available, high-performance site-to-site VPN solution that can be used to connect multiple network environments.

It uses WireGuard, a modern and secure VPN protocol, to provide encrypted and authenticated tunnels. It also uses BIRD and Keepalived to provide network high availability and link redundancy using OSPF, ECMP, and VRRP.

## High-level overview of WireGuard gateway charm deployment

The following diagram shows a typical deployment of the WireGuard gateway charm in three separate network environments, each containing a WireGuard gateway charm. The three WireGuard gateway charms are integrated with charm relations and forward traffic between the three network environments through encrypted WireGuard tunnels.

## Charm architecture

The following diagram shows the architecture of the WireGuard gateway charm:

![WireGuard gateway charm architecture diagram](reference/wireguard-gateway-charm.png)

## Metrics

The WireGuard gateway charm provides Prometheus metrics. The full list of metrics can be found [here](https://canonical.com/juju/docs/wireguard-gateway-charm/latest/reference/metrics/index.html.md).

## Juju events

For this charm, the following Juju events are observed:

1. [config-changed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-config-changed)
2. [upgrade-charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-upgrade-charm)
3. [update-status](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-update-status)
4. [wireguard-router-a-relation-changed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-changed)
5. [wireguard-router-a-relation-broken](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-broken)
6. [wireguard-router-a-relation-joined](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-joined)
7. [wireguard-router-a-relation-departed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-departed)
8. [wireguard-router-b-relation-changed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-changed)
9. [wireguard-router-b-relation-broken](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-broken)
10. [wireguard-router-b-relation-joined](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-joined)
11. [wireguard-router-b-relation-departed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-departed)

During all of those events, the charm runs the same reconciliation process to update the configuration, including relation data, WireGuard configuration, BIRD configuration, and Keepalived configuration, based on the current charm configuration and remote relation data.

#### NOTE
See more in the Juju docs: [Hook](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook)

## Charm code overview

The `src/charm.py` file is the default entry point for the WireGuard gateway charm. It creates an instance of the `Charm` class, which inherits from `ops.CharmBase`. `ops.CharmBase` is the base class from which all charms are derived, provided by [Ops](https://ops.readthedocs.io/en/latest/index.html) (the Python framework for developing charms).

#### NOTE
See more in the Juju docs: [Charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/charm/#charm)

The `__init__` method of `Charm` ensures that the charm observes
and handles all events relevant to its operation.

For example, when a configuration is changed using the CLI:

1. The user runs the configuration command:

```bash
juju config wireguard-gateway advertise-prefixes="10.0.0.0/8"
```

1. A `config-changed` event is emitted.
2. In the `__init__` method, the handler for this event is defined as follows:

```python
self.framework.observe(self.on.config_changed, self.reconcile)
```

1. The `reconcile` method, in turn, takes the necessary actions, such as updating relation(s) and updating WireGuard/BIRD/Keepalived configurations.
