# Lotty A/B Platform

Service for managing A/B testing experiments. Drive your tests without breaking user experience!_)

## 🎨 Artifacts

### ADR

[ADR](./ADR/README.md)

### Runbook

[RUNBOOK.md](./RUNBOOK.md)

### Diagrams

#### C4 Context

![C4 context](./assets/plantuml/rendered/c4_context.png)

Source: [C4 context](./assets/plantuml/raw/c4-context.puml)

#### C4 Container

![C4 container](./assets/plantuml/rendered/c4_container.png)

Source: [C4 container](./assets/plantuml/raw/c4-container.puml)

#### C4 Component

![C4 component](./assets/plantuml/rendered/c4_component.png)

Source: [C4 component](./assets/plantuml/raw/c4-component-critical-path.puml)

### Testing report

Can be seen in GitLab CI/CD pipeline run

1. Go to the [pipelines page](https://gitlab.prodcontest.com/2026-final-users/backend/itq.dev/-/pipelines)
2. Click on the latest pipeline run
![pipeline run](./assets/images/pipeline.png)
3. Testing report (`Tests` tab)
![testing report](./assets/images/testing_report.png)
4. Tests coverage (`Jobs` tab)
![tests coverage](./assets/images/tests_coverage.png)

Here on screenshot you can see coverage percent (`97%`), for detailed coverage per file go to the `test` job log

![tests coverage per file](./assets/images/tests_coverage_per_file.png)

Here we can see statements coverage per file, you can check out job run artifacts for html report.

![tests coverage html report](./assets/images/tests_coverage_report_html.png)

Click here on `index.html` and you'll see complete coverage html report.

### Repository map

[MAP.md](./MAP.md)

Yep, artifacts content is written in Russian, but all other docs are in English, this is for judges' convenient experience.

## 📋 Instructions

### Dedicated services setup

[Backend](./src/backend/README.md)

### Setup with docker compose

#### Warning

Please note that by default containers will use ports 80 (reverse proxy) and range 14601-14611 (for direct access to containers), so there is must be no listeners on this ports range. You can customize the ports in [.env.template](./.env.template).

#### 0. Prerequisites

- [Docker](https://www.docker.com/)  (latest version recommended)
- [Docker compose](https://www.docker.com/)  (latest version recommended)
- Cloned repository

#### 1. Configuration

- Docker compose configuration files are stored in [deploy/compose](./deploy/compose).
- Configuration files for containers are stored in [infrastructure/configs](./infrastructure/configs).
Env could be customized by creating `.env` file in each service config directory, it will automatically override the default values from `.env.template`.
- Ports on which containers will be accessible are defined in [.env.template](./.env.template). This could be customized by creating `.env` file in the root directory and patching the following lines compose you are running:

```yaml
x-defaults: &defaults
  project_directory: ./
  env_file:
    - ./.env.template
    - ./.env # add this
```

#### 2. Choosing compose configuration

- [compose.yaml](./compose.yaml) - default configuration with base services included.
- [compose.prod.yaml](./compose.prod.yaml) - configuration for production environment with full observability stack.

#### 3. Running compose configuration

To run the compose configuration, use the following command:

```bash
docker compose -f compose.yaml up
# OR
docker compose -f compose.prod.yaml --profile observability up
```

That's it, project is already preconfigured for running, so no changes before running this are required.

## Linting && formatting

Instructions [here](./src/backend/README.md#linting--formatting).

Example run:
![style](./assets/images/style.png)

## Observability

### Structured logs

![logs](./assets/images/logs.png)

### Health/ready endpoints (`/health`/`/ready`)

![health](./assets/images/health.png)
![ready](./assets/images/ready.png)

### Metrics (`/metrics`)

![metrics](./assets/images/metrics.png)

System metrics (gc, requests, etc.) and several business metrics (`lotty_decide_requests_total`, `lotty_events_ingested_total`).

### OTEL

You can enable full observability for backend by setting `OTEL_ENABLED=True` in `.env`, also you need to run `compose.prod.yaml` with `observability` profile in order to deploy full observability stack

## Load testing (k6)

Reproducible k6 profile for `POST /api/v1/decide`:

- scenario script: [infrastructure/k6/decide.js](./infrastructure/k6/decide.js)
- runner: [infrastructure/k6/run-decide.sh](./infrastructure/k6/run-decide.sh)
- guide: [infrastructure/k6/README.md](./infrastructure/k6/README.md)